From fc22b3d6507c6745911b9dfcc68f1e665ae13dbc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:43:11 +0200 Subject: Adding upstream version 4.22.0. Signed-off-by: Daniel Baumann --- upstream/archlinux/man3p/FD_CLR.3p | 43 + upstream/archlinux/man3p/_Exit.3p | 461 ++++++ upstream/archlinux/man3p/_longjmp.3p | 132 ++ upstream/archlinux/man3p/_tolower.3p | 74 + upstream/archlinux/man3p/_toupper.3p | 74 + upstream/archlinux/man3p/a64l.3p | 161 +++ upstream/archlinux/man3p/abort.3p | 136 ++ upstream/archlinux/man3p/abs.3p | 72 + upstream/archlinux/man3p/accept.3p | 197 +++ upstream/archlinux/man3p/access.3p | 369 +++++ upstream/archlinux/man3p/acos.3p | 122 ++ upstream/archlinux/man3p/acosh.3p | 120 ++ upstream/archlinux/man3p/acosl.3p | 40 + upstream/archlinux/man3p/aio_cancel.3p | 120 ++ upstream/archlinux/man3p/aio_error.3p | 119 ++ upstream/archlinux/man3p/aio_fsync.3p | 201 +++ upstream/archlinux/man3p/aio_read.3p | 210 +++ upstream/archlinux/man3p/aio_return.3p | 122 ++ upstream/archlinux/man3p/aio_suspend.3p | 134 ++ upstream/archlinux/man3p/aio_write.3p | 220 +++ upstream/archlinux/man3p/alarm.3p | 165 +++ upstream/archlinux/man3p/alphasort.3p | 268 ++++ upstream/archlinux/man3p/asctime.3p | 199 +++ upstream/archlinux/man3p/asin.3p | 158 +++ upstream/archlinux/man3p/asinh.3p | 125 ++ upstream/archlinux/man3p/asinl.3p | 40 + upstream/archlinux/man3p/assert.3p | 94 ++ upstream/archlinux/man3p/atan.3p | 133 ++ upstream/archlinux/man3p/atan2.3p | 241 ++++ upstream/archlinux/man3p/atanf.3p | 40 + upstream/archlinux/man3p/atanh.3p | 176 +++ upstream/archlinux/man3p/atanl.3p | 40 + upstream/archlinux/man3p/atexit.3p | 133 ++ upstream/archlinux/man3p/atof.3p | 87 ++ upstream/archlinux/man3p/atoi.3p | 110 ++ upstream/archlinux/man3p/atol.3p | 98 ++ upstream/archlinux/man3p/basename.3p | 166 +++ upstream/archlinux/man3p/bind.3p | 294 ++++ upstream/archlinux/man3p/bsearch.3p | 195 +++ upstream/archlinux/man3p/btowc.3p | 87 ++ upstream/archlinux/man3p/cabs.3p | 66 + upstream/archlinux/man3p/cacos.3p | 71 + upstream/archlinux/man3p/cacosh.3p | 71 + upstream/archlinux/man3p/cacosl.3p | 40 + upstream/archlinux/man3p/calloc.3p | 116 ++ upstream/archlinux/man3p/carg.3p | 71 + upstream/archlinux/man3p/casin.3p | 71 + upstream/archlinux/man3p/casinh.3p | 72 + upstream/archlinux/man3p/casinl.3p | 40 + upstream/archlinux/man3p/catan.3p | 71 + upstream/archlinux/man3p/catanh.3p | 72 + upstream/archlinux/man3p/catanl.3p | 40 + upstream/archlinux/man3p/catclose.3p | 79 ++ upstream/archlinux/man3p/catgets.3p | 127 ++ upstream/archlinux/man3p/catopen.3p | 208 +++ upstream/archlinux/man3p/cbrt.3p | 83 ++ upstream/archlinux/man3p/ccos.3p | 67 + upstream/archlinux/man3p/ccosh.3p | 67 + upstream/archlinux/man3p/ccosl.3p | 40 + upstream/archlinux/man3p/ceil.3p | 103 ++ upstream/archlinux/man3p/cexp.3p | 69 + upstream/archlinux/man3p/cfgetispeed.3p | 128 ++ upstream/archlinux/man3p/cfgetospeed.3p | 77 + upstream/archlinux/man3p/cfsetispeed.3p | 96 ++ upstream/archlinux/man3p/cfsetospeed.3p | 96 ++ upstream/archlinux/man3p/chdir.3p | 133 ++ upstream/archlinux/man3p/chmod.3p | 372 +++++ upstream/archlinux/man3p/chown.3p | 336 +++++ upstream/archlinux/man3p/cimag.3p | 80 ++ upstream/archlinux/man3p/clearerr.3p | 75 + upstream/archlinux/man3p/clock.3p | 107 ++ upstream/archlinux/man3p/clock_getcpuclockid.3p | 100 ++ upstream/archlinux/man3p/clock_getres.3p | 286 ++++ upstream/archlinux/man3p/clock_nanosleep.3p | 267 ++++ upstream/archlinux/man3p/clock_settime.3p | 40 + upstream/archlinux/man3p/clog.3p | 73 + upstream/archlinux/man3p/close.3p | 356 +++++ upstream/archlinux/man3p/closedir.3p | 110 ++ upstream/archlinux/man3p/closelog.3p | 293 ++++ upstream/archlinux/man3p/confstr.3p | 283 ++++ upstream/archlinux/man3p/conj.3p | 71 + upstream/archlinux/man3p/connect.3p | 303 ++++ upstream/archlinux/man3p/copysign.3p | 76 + upstream/archlinux/man3p/cos.3p | 128 ++ upstream/archlinux/man3p/cosh.3p | 119 ++ upstream/archlinux/man3p/cosl.3p | 40 + upstream/archlinux/man3p/cpow.3p | 70 + upstream/archlinux/man3p/cproj.3p | 106 ++ upstream/archlinux/man3p/creal.3p | 81 ++ upstream/archlinux/man3p/creat.3p | 106 ++ upstream/archlinux/man3p/crypt.3p | 165 +++ upstream/archlinux/man3p/csin.3p | 67 + upstream/archlinux/man3p/csinh.3p | 67 + upstream/archlinux/man3p/csinl.3p | 40 + upstream/archlinux/man3p/csqrt.3p | 70 + upstream/archlinux/man3p/ctan.3p | 67 + upstream/archlinux/man3p/ctanh.3p | 67 + upstream/archlinux/man3p/ctanl.3p | 40 + upstream/archlinux/man3p/ctermid.3p | 148 ++ upstream/archlinux/man3p/ctime.3p | 183 +++ upstream/archlinux/man3p/daylight.3p | 40 + upstream/archlinux/man3p/dbm_clearerr.3p | 405 ++++++ upstream/archlinux/man3p/difftime.3p | 80 ++ upstream/archlinux/man3p/dirfd.3p | 124 ++ upstream/archlinux/man3p/dirname.3p | 174 +++ upstream/archlinux/man3p/div.3p | 90 ++ upstream/archlinux/man3p/dlclose.3p | 143 ++ upstream/archlinux/man3p/dlerror.3p | 112 ++ upstream/archlinux/man3p/dlopen.3p | 270 ++++ upstream/archlinux/man3p/dlsym.3p | 192 +++ upstream/archlinux/man3p/dprintf.3p | 39 + upstream/archlinux/man3p/drand48.3p | 244 ++++ upstream/archlinux/man3p/dup.3p | 264 ++++ upstream/archlinux/man3p/duplocale.3p | 152 ++ upstream/archlinux/man3p/encrypt.3p | 121 ++ upstream/archlinux/man3p/endgrent.3p | 174 +++ upstream/archlinux/man3p/endhostent.3p | 113 ++ upstream/archlinux/man3p/endnetent.3p | 147 ++ upstream/archlinux/man3p/endprotoent.3p | 141 ++ upstream/archlinux/man3p/endpwent.3p | 208 +++ upstream/archlinux/man3p/endservent.3p | 173 +++ upstream/archlinux/man3p/endutxent.3p | 240 ++++ upstream/archlinux/man3p/environ.3p | 40 + upstream/archlinux/man3p/erand48.3p | 40 + upstream/archlinux/man3p/erf.3p | 153 ++ upstream/archlinux/man3p/erfc.3p | 136 ++ upstream/archlinux/man3p/erff.3p | 42 + upstream/archlinux/man3p/errno.3p | 108 ++ upstream/archlinux/man3p/exec.3p | 1357 ++++++++++++++++++ upstream/archlinux/man3p/exit.3p | 113 ++ upstream/archlinux/man3p/exp.3p | 174 +++ upstream/archlinux/man3p/exp2.3p | 153 ++ upstream/archlinux/man3p/expm1.3p | 184 +++ upstream/archlinux/man3p/fabs.3p | 121 ++ upstream/archlinux/man3p/faccessat.3p | 41 + upstream/archlinux/man3p/fattach.3p | 236 ++++ upstream/archlinux/man3p/fchdir.3p | 103 ++ upstream/archlinux/man3p/fchmod.3p | 161 +++ upstream/archlinux/man3p/fchmodat.3p | 40 + upstream/archlinux/man3p/fchown.3p | 140 ++ upstream/archlinux/man3p/fchownat.3p | 42 + upstream/archlinux/man3p/fclose.3p | 206 +++ upstream/archlinux/man3p/fcntl.3p | 756 ++++++++++ upstream/archlinux/man3p/fdatasync.3p | 103 ++ upstream/archlinux/man3p/fdetach.3p | 176 +++ upstream/archlinux/man3p/fdim.3p | 150 ++ upstream/archlinux/man3p/fdopen.3p | 196 +++ upstream/archlinux/man3p/fdopendir.3p | 316 +++++ upstream/archlinux/man3p/feclearexcept.3p | 71 + upstream/archlinux/man3p/fegetenv.3p | 91 ++ upstream/archlinux/man3p/fegetexceptflag.3p | 96 ++ upstream/archlinux/man3p/fegetround.3p | 105 ++ upstream/archlinux/man3p/feholdexcept.3p | 78 + upstream/archlinux/man3p/feof.3p | 80 ++ upstream/archlinux/man3p/feraiseexcept.3p | 91 ++ upstream/archlinux/man3p/ferror.3p | 79 ++ upstream/archlinux/man3p/fesetenv.3p | 40 + upstream/archlinux/man3p/fesetexceptflag.3p | 40 + upstream/archlinux/man3p/fesetround.3p | 40 + upstream/archlinux/man3p/fetestexcept.3p | 97 ++ upstream/archlinux/man3p/feupdateenv.3p | 100 ++ upstream/archlinux/man3p/fexecve.3p | 39 + upstream/archlinux/man3p/fflush.3p | 217 +++ upstream/archlinux/man3p/ffs.3p | 68 + upstream/archlinux/man3p/fgetc.3p | 177 +++ upstream/archlinux/man3p/fgetpos.3p | 103 ++ upstream/archlinux/man3p/fgets.3p | 182 +++ upstream/archlinux/man3p/fgetwc.3p | 176 +++ upstream/archlinux/man3p/fgetws.3p | 123 ++ upstream/archlinux/man3p/fileno.3p | 96 ++ upstream/archlinux/man3p/flockfile.3p | 204 +++ upstream/archlinux/man3p/floor.3p | 99 ++ upstream/archlinux/man3p/fma.3p | 211 +++ upstream/archlinux/man3p/fmax.3p | 80 ++ upstream/archlinux/man3p/fmemopen.3p | 299 ++++ upstream/archlinux/man3p/fmin.3p | 80 ++ upstream/archlinux/man3p/fmod.3p | 170 +++ upstream/archlinux/man3p/fmtmsg.3p | 249 ++++ upstream/archlinux/man3p/fnmatch.3p | 204 +++ upstream/archlinux/man3p/fopen.3p | 358 +++++ upstream/archlinux/man3p/fork.3p | 433 ++++++ upstream/archlinux/man3p/fpathconf.3p | 514 +++++++ upstream/archlinux/man3p/fpclassify.3p | 75 + upstream/archlinux/man3p/fprintf.3p | 1491 ++++++++++++++++++++ upstream/archlinux/man3p/fputc.3p | 159 +++ upstream/archlinux/man3p/fputs.3p | 156 ++ upstream/archlinux/man3p/fputwc.3p | 164 +++ upstream/archlinux/man3p/fputws.3p | 115 ++ upstream/archlinux/man3p/fread.3p | 193 +++ upstream/archlinux/man3p/free.3p | 86 ++ upstream/archlinux/man3p/freeaddrinfo.3p | 556 ++++++++ upstream/archlinux/man3p/freelocale.3p | 104 ++ upstream/archlinux/man3p/freopen.3p | 365 +++++ upstream/archlinux/man3p/frexp.3p | 99 ++ upstream/archlinux/man3p/fscanf.3p | 883 ++++++++++++ upstream/archlinux/man3p/fseek.3p | 252 ++++ upstream/archlinux/man3p/fsetpos.3p | 174 +++ upstream/archlinux/man3p/fstat.3p | 194 +++ upstream/archlinux/man3p/fstatat.3p | 481 +++++++ upstream/archlinux/man3p/fstatvfs.3p | 235 +++ upstream/archlinux/man3p/fsync.3p | 154 ++ upstream/archlinux/man3p/ftell.3p | 131 ++ upstream/archlinux/man3p/ftok.3p | 195 +++ upstream/archlinux/man3p/ftruncate.3p | 163 +++ upstream/archlinux/man3p/ftrylockfile.3p | 40 + upstream/archlinux/man3p/ftw.3p | 286 ++++ upstream/archlinux/man3p/funlockfile.3p | 40 + upstream/archlinux/man3p/futimens.3p | 393 ++++++ upstream/archlinux/man3p/fwide.3p | 109 ++ upstream/archlinux/man3p/fwprintf.3p | 1045 ++++++++++++++ upstream/archlinux/man3p/fwrite.3p | 123 ++ upstream/archlinux/man3p/fwscanf.3p | 874 ++++++++++++ upstream/archlinux/man3p/gai_strerror.3p | 98 ++ upstream/archlinux/man3p/getaddrinfo.3p | 44 + upstream/archlinux/man3p/getc.3p | 92 ++ upstream/archlinux/man3p/getc_unlocked.3p | 235 +++ upstream/archlinux/man3p/getchar.3p | 76 + upstream/archlinux/man3p/getchar_unlocked.3p | 40 + upstream/archlinux/man3p/getcwd.3p | 294 ++++ upstream/archlinux/man3p/getdate.3p | 401 ++++++ upstream/archlinux/man3p/getdelim.3p | 235 +++ upstream/archlinux/man3p/getegid.3p | 86 ++ upstream/archlinux/man3p/getenv.3p | 226 +++ upstream/archlinux/man3p/geteuid.3p | 86 ++ upstream/archlinux/man3p/getgid.3p | 86 ++ upstream/archlinux/man3p/getgrent.3p | 40 + upstream/archlinux/man3p/getgrgid.3p | 243 ++++ upstream/archlinux/man3p/getgrnam.3p | 219 +++ upstream/archlinux/man3p/getgroups.3p | 147 ++ upstream/archlinux/man3p/gethostent.3p | 40 + upstream/archlinux/man3p/gethostid.3p | 62 + upstream/archlinux/man3p/gethostname.3p | 75 + upstream/archlinux/man3p/getitimer.3p | 169 +++ upstream/archlinux/man3p/getline.3p | 42 + upstream/archlinux/man3p/getlogin.3p | 229 +++ upstream/archlinux/man3p/getmsg.3p | 412 ++++++ upstream/archlinux/man3p/getnameinfo.3p | 236 ++++ upstream/archlinux/man3p/getnetbyaddr.3p | 44 + upstream/archlinux/man3p/getopt.3p | 462 ++++++ upstream/archlinux/man3p/getpeername.3p | 123 ++ upstream/archlinux/man3p/getpgid.3p | 100 ++ upstream/archlinux/man3p/getpgrp.3p | 82 ++ upstream/archlinux/man3p/getpid.3p | 71 + upstream/archlinux/man3p/getpmsg.3p | 42 + upstream/archlinux/man3p/getppid.3p | 71 + upstream/archlinux/man3p/getpriority.3p | 237 ++++ upstream/archlinux/man3p/getprotobyname.3p | 44 + upstream/archlinux/man3p/getpwent.3p | 40 + upstream/archlinux/man3p/getpwnam.3p | 248 ++++ upstream/archlinux/man3p/getpwuid.3p | 297 ++++ upstream/archlinux/man3p/getrlimit.3p | 252 ++++ upstream/archlinux/man3p/getrusage.3p | 112 ++ upstream/archlinux/man3p/gets.3p | 137 ++ upstream/archlinux/man3p/getservbyname.3p | 44 + upstream/archlinux/man3p/getsid.3p | 88 ++ upstream/archlinux/man3p/getsockname.3p | 123 ++ upstream/archlinux/man3p/getsockopt.3p | 146 ++ upstream/archlinux/man3p/getsubopt.3p | 298 ++++ upstream/archlinux/man3p/gettimeofday.3p | 79 ++ upstream/archlinux/man3p/getuid.3p | 99 ++ upstream/archlinux/man3p/getutxent.3p | 44 + upstream/archlinux/man3p/getwc.3p | 82 ++ upstream/archlinux/man3p/getwchar.3p | 81 ++ upstream/archlinux/man3p/glob.3p | 450 ++++++ upstream/archlinux/man3p/gmtime.3p | 154 ++ upstream/archlinux/man3p/grantpt.3p | 95 ++ upstream/archlinux/man3p/hcreate.3p | 213 +++ upstream/archlinux/man3p/htonl.3p | 92 ++ upstream/archlinux/man3p/hypot.3p | 158 +++ upstream/archlinux/man3p/iconv.3p | 237 ++++ upstream/archlinux/man3p/iconv_close.3p | 76 + upstream/archlinux/man3p/iconv_open.3p | 126 ++ upstream/archlinux/man3p/if_freenameindex.3p | 74 + upstream/archlinux/man3p/if_indextoname.3p | 84 ++ upstream/archlinux/man3p/if_nameindex.3p | 84 ++ upstream/archlinux/man3p/if_nametoindex.3p | 67 + upstream/archlinux/man3p/ilogb.3p | 195 +++ upstream/archlinux/man3p/imaxabs.3p | 69 + upstream/archlinux/man3p/imaxdiv.3p | 78 + upstream/archlinux/man3p/inet_addr.3p | 118 ++ upstream/archlinux/man3p/inet_ntop.3p | 202 +++ upstream/archlinux/man3p/initstate.3p | 194 +++ upstream/archlinux/man3p/insque.3p | 216 +++ upstream/archlinux/man3p/ioctl.3p | 1216 ++++++++++++++++ upstream/archlinux/man3p/isalnum.3p | 118 ++ upstream/archlinux/man3p/isalpha.3p | 117 ++ upstream/archlinux/man3p/isascii.3p | 73 + upstream/archlinux/man3p/isastream.3p | 77 + upstream/archlinux/man3p/isatty.3p | 84 ++ upstream/archlinux/man3p/isblank.3p | 119 ++ upstream/archlinux/man3p/iscntrl.3p | 117 ++ upstream/archlinux/man3p/isdigit.3p | 115 ++ upstream/archlinux/man3p/isfinite.3p | 75 + upstream/archlinux/man3p/isgraph.3p | 118 ++ upstream/archlinux/man3p/isgreater.3p | 103 ++ upstream/archlinux/man3p/isgreaterequal.3p | 103 ++ upstream/archlinux/man3p/isinf.3p | 74 + upstream/archlinux/man3p/isless.3p | 103 ++ upstream/archlinux/man3p/islessequal.3p | 103 ++ upstream/archlinux/man3p/islessgreater.3p | 108 ++ upstream/archlinux/man3p/islower.3p | 171 +++ upstream/archlinux/man3p/isnan.3p | 74 + upstream/archlinux/man3p/isnormal.3p | 74 + upstream/archlinux/man3p/isprint.3p | 117 ++ upstream/archlinux/man3p/ispunct.3p | 117 ++ upstream/archlinux/man3p/isspace.3p | 116 ++ upstream/archlinux/man3p/isunordered.3p | 89 ++ upstream/archlinux/man3p/isupper.3p | 117 ++ upstream/archlinux/man3p/iswalnum.3p | 119 ++ upstream/archlinux/man3p/iswalpha.3p | 116 ++ upstream/archlinux/man3p/iswblank.3p | 117 ++ upstream/archlinux/man3p/iswcntrl.3p | 116 ++ upstream/archlinux/man3p/iswctype.3p | 192 +++ upstream/archlinux/man3p/iswdigit.3p | 116 ++ upstream/archlinux/man3p/iswgraph.3p | 117 ++ upstream/archlinux/man3p/iswlower.3p | 116 ++ upstream/archlinux/man3p/iswprint.3p | 116 ++ upstream/archlinux/man3p/iswpunct.3p | 116 ++ upstream/archlinux/man3p/iswspace.3p | 116 ++ upstream/archlinux/man3p/iswupper.3p | 116 ++ upstream/archlinux/man3p/iswxdigit.3p | 116 ++ upstream/archlinux/man3p/isxdigit.3p | 114 ++ upstream/archlinux/man3p/j0.3p | 114 ++ upstream/archlinux/man3p/jrand48.3p | 40 + upstream/archlinux/man3p/kill.3p | 290 ++++ upstream/archlinux/man3p/killpg.3p | 97 ++ upstream/archlinux/man3p/l64a.3p | 40 + upstream/archlinux/man3p/labs.3p | 86 ++ upstream/archlinux/man3p/lchown.3p | 176 +++ upstream/archlinux/man3p/lcong48.3p | 41 + upstream/archlinux/man3p/ldexp.3p | 153 ++ upstream/archlinux/man3p/ldiv.3p | 110 ++ upstream/archlinux/man3p/lfind.3p | 41 + upstream/archlinux/man3p/lgamma.3p | 160 +++ upstream/archlinux/man3p/link.3p | 470 ++++++ upstream/archlinux/man3p/lio_listio.3p | 356 +++++ upstream/archlinux/man3p/listen.3p | 155 ++ upstream/archlinux/man3p/llabs.3p | 40 + upstream/archlinux/man3p/lldiv.3p | 40 + upstream/archlinux/man3p/llrint.3p | 149 ++ upstream/archlinux/man3p/llround.3p | 151 ++ upstream/archlinux/man3p/localeconv.3p | 367 +++++ upstream/archlinux/man3p/localtime.3p | 286 ++++ upstream/archlinux/man3p/lockf.3p | 293 ++++ upstream/archlinux/man3p/log.3p | 153 ++ upstream/archlinux/man3p/log10.3p | 151 ++ upstream/archlinux/man3p/log1p.3p | 179 +++ upstream/archlinux/man3p/log2.3p | 150 ++ upstream/archlinux/man3p/logb.3p | 165 +++ upstream/archlinux/man3p/logf.3p | 42 + upstream/archlinux/man3p/longjmp.3p | 176 +++ upstream/archlinux/man3p/lrand48.3p | 41 + upstream/archlinux/man3p/lrint.3p | 149 ++ upstream/archlinux/man3p/lround.3p | 151 ++ upstream/archlinux/man3p/lsearch.3p | 156 ++ upstream/archlinux/man3p/lseek.3p | 185 +++ upstream/archlinux/man3p/lstat.3p | 40 + upstream/archlinux/man3p/malloc.3p | 111 ++ upstream/archlinux/man3p/mblen.3p | 139 ++ upstream/archlinux/man3p/mbrlen.3p | 164 +++ upstream/archlinux/man3p/mbrtowc.3p | 185 +++ upstream/archlinux/man3p/mbsinit.3p | 103 ++ upstream/archlinux/man3p/mbsrtowcs.3p | 188 +++ upstream/archlinux/man3p/mbstowcs.3p | 123 ++ upstream/archlinux/man3p/mbtowc.3p | 143 ++ upstream/archlinux/man3p/memccpy.3p | 83 ++ upstream/archlinux/man3p/memchr.3p | 83 ++ upstream/archlinux/man3p/memcmp.3p | 84 ++ upstream/archlinux/man3p/memcpy.3p | 76 + upstream/archlinux/man3p/memmove.3p | 85 ++ upstream/archlinux/man3p/memset.3p | 73 + upstream/archlinux/man3p/mkdir.3p | 264 ++++ upstream/archlinux/man3p/mkdtemp.3p | 249 ++++ upstream/archlinux/man3p/mkfifo.3p | 282 ++++ upstream/archlinux/man3p/mknod.3p | 345 +++++ upstream/archlinux/man3p/mkstemp.3p | 40 + upstream/archlinux/man3p/mktime.3p | 187 +++ upstream/archlinux/man3p/mlock.3p | 170 +++ upstream/archlinux/man3p/mlockall.3p | 160 +++ upstream/archlinux/man3p/mmap.3p | 736 ++++++++++ upstream/archlinux/man3p/modf.3p | 109 ++ upstream/archlinux/man3p/mprotect.3p | 160 +++ upstream/archlinux/man3p/mq_close.3p | 92 ++ upstream/archlinux/man3p/mq_getattr.3p | 113 ++ upstream/archlinux/man3p/mq_notify.3p | 198 +++ upstream/archlinux/man3p/mq_open.3p | 319 +++++ upstream/archlinux/man3p/mq_receive.3p | 203 +++ upstream/archlinux/man3p/mq_send.3p | 212 +++ upstream/archlinux/man3p/mq_setattr.3p | 114 ++ upstream/archlinux/man3p/mq_timedreceive.3p | 44 + upstream/archlinux/man3p/mq_timedsend.3p | 43 + upstream/archlinux/man3p/mq_unlink.3p | 135 ++ upstream/archlinux/man3p/mrand48.3p | 40 + upstream/archlinux/man3p/msgctl.3p | 190 +++ upstream/archlinux/man3p/msgget.3p | 166 +++ upstream/archlinux/man3p/msgrcv.3p | 274 ++++ upstream/archlinux/man3p/msgsnd.3p | 241 ++++ upstream/archlinux/man3p/msync.3p | 193 +++ upstream/archlinux/man3p/munlock.3p | 40 + upstream/archlinux/man3p/munlockall.3p | 40 + upstream/archlinux/man3p/munmap.3p | 145 ++ upstream/archlinux/man3p/nan.3p | 114 ++ upstream/archlinux/man3p/nanosleep.3p | 147 ++ upstream/archlinux/man3p/nearbyint.3p | 91 ++ upstream/archlinux/man3p/newlocale.3p | 267 ++++ upstream/archlinux/man3p/nextafter.3p | 198 +++ upstream/archlinux/man3p/nftw.3p | 360 +++++ upstream/archlinux/man3p/nice.3p | 124 ++ upstream/archlinux/man3p/nl_langinfo.3p | 209 +++ upstream/archlinux/man3p/nrand48.3p | 40 + upstream/archlinux/man3p/ntohl.3p | 42 + upstream/archlinux/man3p/open.3p | 794 +++++++++++ upstream/archlinux/man3p/open_memstream.3p | 204 +++ upstream/archlinux/man3p/openat.3p | 40 + upstream/archlinux/man3p/opendir.3p | 40 + upstream/archlinux/man3p/openlog.3p | 40 + upstream/archlinux/man3p/optarg.3p | 44 + upstream/archlinux/man3p/pathconf.3p | 40 + upstream/archlinux/man3p/pause.3p | 93 ++ upstream/archlinux/man3p/pclose.3p | 227 +++ upstream/archlinux/man3p/perror.3p | 158 +++ upstream/archlinux/man3p/pipe.3p | 174 +++ upstream/archlinux/man3p/poll.3p | 401 ++++++ upstream/archlinux/man3p/popen.3p | 314 +++++ upstream/archlinux/man3p/posix_fadvise.3p | 135 ++ upstream/archlinux/man3p/posix_fallocate.3p | 162 +++ upstream/archlinux/man3p/posix_madvise.3p | 146 ++ upstream/archlinux/man3p/posix_mem_offset.3p | 127 ++ upstream/archlinux/man3p/posix_memalign.3p | 149 ++ upstream/archlinux/man3p/posix_openpt.3p | 177 +++ upstream/archlinux/man3p/posix_spawn.3p | 936 ++++++++++++ .../man3p/posix_spawn_file_actions_addclose.3p | 330 +++++ .../man3p/posix_spawn_file_actions_adddup2.3p | 137 ++ .../man3p/posix_spawn_file_actions_addopen.3p | 43 + .../man3p/posix_spawn_file_actions_destroy.3p | 111 ++ .../archlinux/man3p/posix_spawnattr_destroy.3p | 153 ++ .../archlinux/man3p/posix_spawnattr_getflags.3p | 131 ++ .../archlinux/man3p/posix_spawnattr_getpgroup.3p | 116 ++ .../man3p/posix_spawnattr_getschedparam.3p | 121 ++ .../man3p/posix_spawnattr_getschedpolicy.3p | 120 ++ .../man3p/posix_spawnattr_getsigdefault.3p | 121 ++ .../archlinux/man3p/posix_spawnattr_getsigmask.3p | 119 ++ upstream/archlinux/man3p/posix_spawnattr_init.3p | 41 + .../archlinux/man3p/posix_spawnattr_setflags.3p | 41 + .../archlinux/man3p/posix_spawnattr_setpgroup.3p | 41 + .../man3p/posix_spawnattr_setschedparam.3p | 43 + .../man3p/posix_spawnattr_setschedpolicy.3p | 43 + .../man3p/posix_spawnattr_setsigdefault.3p | 43 + .../archlinux/man3p/posix_spawnattr_setsigmask.3p | 43 + upstream/archlinux/man3p/posix_spawnp.3p | 44 + .../archlinux/man3p/posix_trace_attr_destroy.3p | 127 ++ .../man3p/posix_trace_attr_getclockres.3p | 192 +++ .../man3p/posix_trace_attr_getinherited.3p | 279 ++++ .../archlinux/man3p/posix_trace_attr_getlogsize.3p | 267 ++++ .../archlinux/man3p/posix_trace_attr_getname.3p | 42 + .../man3p/posix_trace_attr_getstreamfullpolicy.3p | 42 + .../man3p/posix_trace_attr_getstreamsize.3p | 43 + upstream/archlinux/man3p/posix_trace_attr_init.3p | 41 + .../man3p/posix_trace_attr_setinherited.3p | 45 + .../archlinux/man3p/posix_trace_attr_setlogsize.3p | 46 + .../archlinux/man3p/posix_trace_attr_setname.3p | 42 + .../man3p/posix_trace_attr_setstreamfullpolicy.3p | 42 + .../man3p/posix_trace_attr_setstreamsize.3p | 43 + upstream/archlinux/man3p/posix_trace_clear.3p | 127 ++ upstream/archlinux/man3p/posix_trace_close.3p | 175 +++ upstream/archlinux/man3p/posix_trace_create.3p | 452 ++++++ upstream/archlinux/man3p/posix_trace_event.3p | 180 +++ .../archlinux/man3p/posix_trace_eventid_equal.3p | 227 +++ .../archlinux/man3p/posix_trace_eventid_open.3p | 43 + .../archlinux/man3p/posix_trace_eventset_add.3p | 157 +++ .../man3p/posix_trace_eventtypelist_getnext_id.3p | 111 ++ upstream/archlinux/man3p/posix_trace_flush.3p | 42 + upstream/archlinux/man3p/posix_trace_get_attr.3p | 140 ++ upstream/archlinux/man3p/posix_trace_get_filter.3p | 145 ++ upstream/archlinux/man3p/posix_trace_get_status.3p | 42 + .../archlinux/man3p/posix_trace_getnext_event.3p | 267 ++++ upstream/archlinux/man3p/posix_trace_open.3p | 43 + upstream/archlinux/man3p/posix_trace_set_filter.3p | 42 + upstream/archlinux/man3p/posix_trace_shutdown.3p | 42 + upstream/archlinux/man3p/posix_trace_start.3p | 105 ++ .../man3p/posix_trace_timedgetnext_event.3p | 46 + .../man3p/posix_trace_trid_eventid_open.3p | 43 + .../man3p/posix_trace_trygetnext_event.3p | 45 + .../archlinux/man3p/posix_typed_mem_get_info.3p | 144 ++ upstream/archlinux/man3p/posix_typed_mem_open.3p | 279 ++++ upstream/archlinux/man3p/pow.3p | 317 +++++ upstream/archlinux/man3p/pread.3p | 40 + upstream/archlinux/man3p/printf.3p | 40 + upstream/archlinux/man3p/pselect.3p | 507 +++++++ upstream/archlinux/man3p/psiginfo.3p | 179 +++ upstream/archlinux/man3p/pthread_atfork.3p | 262 ++++ upstream/archlinux/man3p/pthread_attr_destroy.3p | 239 ++++ .../archlinux/man3p/pthread_attr_getdetachstate.3p | 175 +++ .../archlinux/man3p/pthread_attr_getguardsize.3p | 217 +++ .../man3p/pthread_attr_getinheritsched.3p | 161 +++ .../archlinux/man3p/pthread_attr_getschedparam.3p | 152 ++ .../archlinux/man3p/pthread_attr_getschedpolicy.3p | 135 ++ upstream/archlinux/man3p/pthread_attr_getscope.3p | 134 ++ upstream/archlinux/man3p/pthread_attr_getstack.3p | 203 +++ .../archlinux/man3p/pthread_attr_getstacksize.3p | 121 ++ upstream/archlinux/man3p/pthread_attr_init.3p | 40 + .../archlinux/man3p/pthread_attr_setdetachstate.3p | 40 + .../archlinux/man3p/pthread_attr_setguardsize.3p | 41 + .../man3p/pthread_attr_setinheritsched.3p | 42 + .../archlinux/man3p/pthread_attr_setschedparam.3p | 41 + .../archlinux/man3p/pthread_attr_setschedpolicy.3p | 41 + upstream/archlinux/man3p/pthread_attr_setscope.3p | 41 + upstream/archlinux/man3p/pthread_attr_setstack.3p | 41 + .../archlinux/man3p/pthread_attr_setstacksize.3p | 40 + .../archlinux/man3p/pthread_barrier_destroy.3p | 165 +++ upstream/archlinux/man3p/pthread_barrier_wait.3p | 114 ++ .../archlinux/man3p/pthread_barrierattr_destroy.3p | 115 ++ .../man3p/pthread_barrierattr_getpshared.3p | 139 ++ .../archlinux/man3p/pthread_barrierattr_init.3p | 40 + .../man3p/pthread_barrierattr_setpshared.3p | 41 + upstream/archlinux/man3p/pthread_cancel.3p | 123 ++ upstream/archlinux/man3p/pthread_cleanup_pop.3p | 343 +++++ upstream/archlinux/man3p/pthread_cond_broadcast.3p | 240 ++++ upstream/archlinux/man3p/pthread_cond_destroy.3p | 228 +++ upstream/archlinux/man3p/pthread_cond_signal.3p | 40 + upstream/archlinux/man3p/pthread_cond_timedwait.3p | 464 ++++++ .../archlinux/man3p/pthread_condattr_destroy.3p | 143 ++ .../archlinux/man3p/pthread_condattr_getclock.3p | 135 ++ .../archlinux/man3p/pthread_condattr_getpshared.3p | 130 ++ upstream/archlinux/man3p/pthread_condattr_init.3p | 40 + .../archlinux/man3p/pthread_condattr_setclock.3p | 41 + .../archlinux/man3p/pthread_condattr_setpshared.3p | 41 + upstream/archlinux/man3p/pthread_create.3p | 238 ++++ upstream/archlinux/man3p/pthread_detach.3p | 121 ++ upstream/archlinux/man3p/pthread_equal.3p | 88 ++ upstream/archlinux/man3p/pthread_exit.3p | 129 ++ upstream/archlinux/man3p/pthread_getconcurrency.3p | 142 ++ upstream/archlinux/man3p/pthread_getcpuclockid.3p | 80 ++ upstream/archlinux/man3p/pthread_getschedparam.3p | 195 +++ upstream/archlinux/man3p/pthread_getspecific.3p | 153 ++ upstream/archlinux/man3p/pthread_join.3p | 232 +++ upstream/archlinux/man3p/pthread_key_create.3p | 263 ++++ upstream/archlinux/man3p/pthread_key_delete.3p | 141 ++ upstream/archlinux/man3p/pthread_kill.3p | 119 ++ .../archlinux/man3p/pthread_mutex_consistent.3p | 122 ++ upstream/archlinux/man3p/pthread_mutex_destroy.3p | 422 ++++++ .../man3p/pthread_mutex_getprioceiling.3p | 153 ++ upstream/archlinux/man3p/pthread_mutex_init.3p | 42 + upstream/archlinux/man3p/pthread_mutex_lock.3p | 312 ++++ .../man3p/pthread_mutex_setprioceiling.3p | 42 + .../archlinux/man3p/pthread_mutex_timedlock.3p | 197 +++ upstream/archlinux/man3p/pthread_mutex_trylock.3p | 42 + .../archlinux/man3p/pthread_mutexattr_destroy.3p | 366 +++++ .../man3p/pthread_mutexattr_getprioceiling.3p | 125 ++ .../man3p/pthread_mutexattr_getprotocol.3p | 199 +++ .../man3p/pthread_mutexattr_getpshared.3p | 129 ++ .../archlinux/man3p/pthread_mutexattr_getrobust.3p | 164 +++ .../archlinux/man3p/pthread_mutexattr_gettype.3p | 137 ++ upstream/archlinux/man3p/pthread_mutexattr_init.3p | 40 + .../man3p/pthread_mutexattr_setprioceiling.3p | 42 + .../man3p/pthread_mutexattr_setprotocol.3p | 42 + .../man3p/pthread_mutexattr_setpshared.3p | 41 + .../archlinux/man3p/pthread_mutexattr_setrobust.3p | 41 + .../archlinux/man3p/pthread_mutexattr_settype.3p | 40 + upstream/archlinux/man3p/pthread_once.3p | 197 +++ upstream/archlinux/man3p/pthread_rwlock_destroy.3p | 186 +++ upstream/archlinux/man3p/pthread_rwlock_rdlock.3p | 184 +++ .../archlinux/man3p/pthread_rwlock_timedrdlock.3p | 150 ++ .../archlinux/man3p/pthread_rwlock_timedwrlock.3p | 143 ++ .../archlinux/man3p/pthread_rwlock_tryrdlock.3p | 40 + .../archlinux/man3p/pthread_rwlock_trywrlock.3p | 136 ++ upstream/archlinux/man3p/pthread_rwlock_unlock.3p | 121 ++ upstream/archlinux/man3p/pthread_rwlock_wrlock.3p | 40 + .../archlinux/man3p/pthread_rwlockattr_destroy.3p | 117 ++ .../man3p/pthread_rwlockattr_getpshared.3p | 122 ++ .../archlinux/man3p/pthread_rwlockattr_init.3p | 40 + .../man3p/pthread_rwlockattr_setpshared.3p | 42 + upstream/archlinux/man3p/pthread_self.3p | 69 + upstream/archlinux/man3p/pthread_setcancelstate.3p | 174 +++ upstream/archlinux/man3p/pthread_setconcurrency.3p | 40 + upstream/archlinux/man3p/pthread_setschedparam.3p | 42 + upstream/archlinux/man3p/pthread_setschedprio.3p | 117 ++ upstream/archlinux/man3p/pthread_setspecific.3p | 40 + upstream/archlinux/man3p/pthread_sigmask.3p | 250 ++++ upstream/archlinux/man3p/pthread_spin_destroy.3p | 152 ++ upstream/archlinux/man3p/pthread_spin_lock.3p | 116 ++ upstream/archlinux/man3p/pthread_spin_unlock.3p | 100 ++ upstream/archlinux/man3p/pthread_testcancel.3p | 40 + upstream/archlinux/man3p/ptsname.3p | 104 ++ upstream/archlinux/man3p/putc.3p | 80 ++ upstream/archlinux/man3p/putc_unlocked.3p | 40 + upstream/archlinux/man3p/putchar.3p | 67 + upstream/archlinux/man3p/putchar_unlocked.3p | 40 + upstream/archlinux/man3p/putenv.3p | 161 +++ upstream/archlinux/man3p/putmsg.3p | 363 +++++ upstream/archlinux/man3p/puts.3p | 147 ++ upstream/archlinux/man3p/pututxline.3p | 40 + upstream/archlinux/man3p/putwc.3p | 82 ++ upstream/archlinux/man3p/putwchar.3p | 68 + upstream/archlinux/man3p/pwrite.3p | 41 + upstream/archlinux/man3p/qsort.3p | 115 ++ upstream/archlinux/man3p/raise.3p | 95 ++ upstream/archlinux/man3p/rand.3p | 231 +++ upstream/archlinux/man3p/random.3p | 40 + upstream/archlinux/man3p/read.3p | 628 +++++++++ upstream/archlinux/man3p/readdir.3p | 377 +++++ upstream/archlinux/man3p/readlink.3p | 262 ++++ upstream/archlinux/man3p/readv.3p | 152 ++ upstream/archlinux/man3p/realloc.3p | 179 +++ upstream/archlinux/man3p/realpath.3p | 256 ++++ upstream/archlinux/man3p/recv.3p | 222 +++ upstream/archlinux/man3p/recvfrom.3p | 245 ++++ upstream/archlinux/man3p/recvmsg.3p | 280 ++++ upstream/archlinux/man3p/regcomp.3p | 875 ++++++++++++ upstream/archlinux/man3p/remainder.3p | 147 ++ upstream/archlinux/man3p/remove.3p | 99 ++ upstream/archlinux/man3p/remque.3p | 40 + upstream/archlinux/man3p/remquo.3p | 163 +++ upstream/archlinux/man3p/rename.3p | 555 ++++++++ upstream/archlinux/man3p/rewind.3p | 102 ++ upstream/archlinux/man3p/rewinddir.3p | 93 ++ upstream/archlinux/man3p/rint.3p | 132 ++ upstream/archlinux/man3p/rmdir.3p | 269 ++++ upstream/archlinux/man3p/round.3p | 90 ++ upstream/archlinux/man3p/scalbln.3p | 174 +++ upstream/archlinux/man3p/scandir.3p | 42 + upstream/archlinux/man3p/scanf.3p | 40 + upstream/archlinux/man3p/sched_get_priority_max.3p | 95 ++ upstream/archlinux/man3p/sched_getparam.3p | 100 ++ upstream/archlinux/man3p/sched_getscheduler.3p | 100 ++ upstream/archlinux/man3p/sched_rr_get_interval.3p | 88 ++ upstream/archlinux/man3p/sched_setparam.3p | 159 +++ upstream/archlinux/man3p/sched_setscheduler.3p | 184 +++ upstream/archlinux/man3p/sched_yield.3p | 69 + upstream/archlinux/man3p/seed48.3p | 41 + upstream/archlinux/man3p/seekdir.3p | 119 ++ upstream/archlinux/man3p/select.3p | 42 + upstream/archlinux/man3p/sem_close.3p | 105 ++ upstream/archlinux/man3p/sem_destroy.3p | 95 ++ upstream/archlinux/man3p/sem_getvalue.3p | 92 ++ upstream/archlinux/man3p/sem_init.3p | 137 ++ upstream/archlinux/man3p/sem_open.3p | 298 ++++ upstream/archlinux/man3p/sem_post.3p | 106 ++ upstream/archlinux/man3p/sem_timedwait.3p | 233 +++ upstream/archlinux/man3p/sem_trywait.3p | 129 ++ upstream/archlinux/man3p/sem_unlink.3p | 135 ++ upstream/archlinux/man3p/sem_wait.3p | 40 + upstream/archlinux/man3p/semctl.3p | 340 +++++ upstream/archlinux/man3p/semget.3p | 198 +++ upstream/archlinux/man3p/semop.3p | 482 +++++++ upstream/archlinux/man3p/send.3p | 226 +++ upstream/archlinux/man3p/sendmsg.3p | 325 +++++ upstream/archlinux/man3p/sendto.3p | 316 +++++ upstream/archlinux/man3p/setbuf.3p | 123 ++ upstream/archlinux/man3p/setegid.3p | 96 ++ upstream/archlinux/man3p/setenv.3p | 169 +++ upstream/archlinux/man3p/seteuid.3p | 95 ++ upstream/archlinux/man3p/setgid.3p | 103 ++ upstream/archlinux/man3p/setgrent.3p | 40 + upstream/archlinux/man3p/sethostent.3p | 40 + upstream/archlinux/man3p/setitimer.3p | 41 + upstream/archlinux/man3p/setjmp.3p | 106 ++ upstream/archlinux/man3p/setkey.3p | 101 ++ upstream/archlinux/man3p/setlocale.3p | 449 ++++++ upstream/archlinux/man3p/setlogmask.3p | 40 + upstream/archlinux/man3p/setnetent.3p | 39 + upstream/archlinux/man3p/setpgid.3p | 203 +++ upstream/archlinux/man3p/setpgrp.3p | 87 ++ upstream/archlinux/man3p/setpriority.3p | 40 + upstream/archlinux/man3p/setprotoent.3p | 40 + upstream/archlinux/man3p/setpwent.3p | 40 + upstream/archlinux/man3p/setregid.3p | 137 ++ upstream/archlinux/man3p/setreuid.3p | 143 ++ upstream/archlinux/man3p/setrlimit.3p | 40 + upstream/archlinux/man3p/setservent.3p | 40 + upstream/archlinux/man3p/setsid.3p | 113 ++ upstream/archlinux/man3p/setsockopt.3p | 167 +++ upstream/archlinux/man3p/setstate.3p | 40 + upstream/archlinux/man3p/setuid.3p | 257 ++++ upstream/archlinux/man3p/setutxent.3p | 40 + upstream/archlinux/man3p/setvbuf.3p | 126 ++ upstream/archlinux/man3p/shm_open.3p | 405 ++++++ upstream/archlinux/man3p/shm_unlink.3p | 141 ++ upstream/archlinux/man3p/shmat.3p | 154 ++ upstream/archlinux/man3p/shmctl.3p | 192 +++ upstream/archlinux/man3p/shmdt.3p | 107 ++ upstream/archlinux/man3p/shmget.3p | 185 +++ upstream/archlinux/man3p/shutdown.3p | 128 ++ upstream/archlinux/man3p/sigaction.3p | 660 +++++++++ upstream/archlinux/man3p/sigaddset.3p | 105 ++ upstream/archlinux/man3p/sigaltstack.3p | 183 +++ upstream/archlinux/man3p/sigdelset.3p | 106 ++ upstream/archlinux/man3p/sigemptyset.3p | 120 ++ upstream/archlinux/man3p/sigfillset.3p | 75 + upstream/archlinux/man3p/sighold.3p | 257 ++++ upstream/archlinux/man3p/siginterrupt.3p | 101 ++ upstream/archlinux/man3p/sigismember.3p | 107 ++ upstream/archlinux/man3p/siglongjmp.3p | 108 ++ upstream/archlinux/man3p/signal.3p | 218 +++ upstream/archlinux/man3p/signbit.3p | 72 + upstream/archlinux/man3p/signgam.3p | 40 + upstream/archlinux/man3p/sigpause.3p | 40 + upstream/archlinux/man3p/sigpending.3p | 74 + upstream/archlinux/man3p/sigprocmask.3p | 41 + upstream/archlinux/man3p/sigqueue.3p | 190 +++ upstream/archlinux/man3p/sigrelse.3p | 42 + upstream/archlinux/man3p/sigsetjmp.3p | 157 +++ upstream/archlinux/man3p/sigsuspend.3p | 130 ++ upstream/archlinux/man3p/sigtimedwait.3p | 363 +++++ upstream/archlinux/man3p/sigwait.3p | 147 ++ upstream/archlinux/man3p/sigwaitinfo.3p | 40 + upstream/archlinux/man3p/sin.3p | 162 +++ upstream/archlinux/man3p/sinh.3p | 147 ++ upstream/archlinux/man3p/sinl.3p | 40 + upstream/archlinux/man3p/sleep.3p | 237 ++++ upstream/archlinux/man3p/snprintf.3p | 41 + upstream/archlinux/man3p/sockatmark.3p | 151 ++ upstream/archlinux/man3p/socket.3p | 186 +++ upstream/archlinux/man3p/socketpair.3p | 178 +++ upstream/archlinux/man3p/sprintf.3p | 40 + upstream/archlinux/man3p/sqrt.3p | 138 ++ upstream/archlinux/man3p/srand.3p | 40 + upstream/archlinux/man3p/srand48.3p | 41 + upstream/archlinux/man3p/srandom.3p | 40 + upstream/archlinux/man3p/sscanf.3p | 40 + upstream/archlinux/man3p/stat.3p | 40 + upstream/archlinux/man3p/statvfs.3p | 40 + upstream/archlinux/man3p/stdin.3p | 131 ++ upstream/archlinux/man3p/stpcpy.3p | 40 + upstream/archlinux/man3p/stpncpy.3p | 40 + upstream/archlinux/man3p/strcasecmp.3p | 137 ++ upstream/archlinux/man3p/strcat.3p | 80 ++ upstream/archlinux/man3p/strchr.3p | 73 + upstream/archlinux/man3p/strcmp.3p | 127 ++ upstream/archlinux/man3p/strcoll.3p | 172 +++ upstream/archlinux/man3p/strcpy.3p | 180 +++ upstream/archlinux/man3p/strcspn.3p | 75 + upstream/archlinux/man3p/strdup.3p | 139 ++ upstream/archlinux/man3p/strerror.3p | 310 ++++ upstream/archlinux/man3p/strfmon.3p | 328 +++++ upstream/archlinux/man3p/strftime.3p | 1004 +++++++++++++ upstream/archlinux/man3p/strlen.3p | 131 ++ upstream/archlinux/man3p/strncasecmp.3p | 43 + upstream/archlinux/man3p/strncat.3p | 80 ++ upstream/archlinux/man3p/strncmp.3p | 84 ++ upstream/archlinux/man3p/strncpy.3p | 118 ++ upstream/archlinux/man3p/strndup.3p | 40 + upstream/archlinux/man3p/strnlen.3p | 40 + upstream/archlinux/man3p/strpbrk.3p | 73 + upstream/archlinux/man3p/strptime.3p | 443 ++++++ upstream/archlinux/man3p/strrchr.3p | 99 ++ upstream/archlinux/man3p/strsignal.3p | 108 ++ upstream/archlinux/man3p/strspn.3p | 71 + upstream/archlinux/man3p/strstr.3p | 76 + upstream/archlinux/man3p/strtod.3p | 345 +++++ upstream/archlinux/man3p/strtoimax.3p | 125 ++ upstream/archlinux/man3p/strtok.3p | 232 +++ upstream/archlinux/man3p/strtol.3p | 248 ++++ upstream/archlinux/man3p/strtold.3p | 40 + upstream/archlinux/man3p/strtoll.3p | 41 + upstream/archlinux/man3p/strtoul.3p | 244 ++++ upstream/archlinux/man3p/strtoumax.3p | 41 + upstream/archlinux/man3p/strxfrm.3p | 156 ++ upstream/archlinux/man3p/swab.3p | 79 ++ upstream/archlinux/man3p/swprintf.3p | 42 + upstream/archlinux/man3p/swscanf.3p | 42 + upstream/archlinux/man3p/symlink.3p | 287 ++++ upstream/archlinux/man3p/sync.3p | 67 + upstream/archlinux/man3p/sysconf.3p | 359 +++++ upstream/archlinux/man3p/syslog.3p | 40 + upstream/archlinux/man3p/system.3p | 476 +++++++ upstream/archlinux/man3p/tan.3p | 208 +++ upstream/archlinux/man3p/tanh.3p | 131 ++ upstream/archlinux/man3p/tanl.3p | 40 + upstream/archlinux/man3p/tcdrain.3p | 99 ++ upstream/archlinux/man3p/tcflow.3p | 135 ++ upstream/archlinux/man3p/tcflush.3p | 112 ++ upstream/archlinux/man3p/tcgetattr.3p | 148 ++ upstream/archlinux/man3p/tcgetpgrp.3p | 92 ++ upstream/archlinux/man3p/tcgetsid.3p | 78 + upstream/archlinux/man3p/tcsendbreak.3p | 105 ++ upstream/archlinux/man3p/tcsetattr.3p | 242 ++++ upstream/archlinux/man3p/tcsetpgrp.3p | 111 ++ upstream/archlinux/man3p/tdelete.3p | 357 +++++ upstream/archlinux/man3p/telldir.3p | 75 + upstream/archlinux/man3p/tempnam.3p | 150 ++ upstream/archlinux/man3p/tfind.3p | 41 + upstream/archlinux/man3p/tgamma.3p | 251 ++++ upstream/archlinux/man3p/time.3p | 209 +++ upstream/archlinux/man3p/timer_create.3p | 265 ++++ upstream/archlinux/man3p/timer_delete.3p | 92 ++ upstream/archlinux/man3p/timer_getoverrun.3p | 275 ++++ upstream/archlinux/man3p/times.3p | 214 +++ upstream/archlinux/man3p/timezone.3p | 40 + upstream/archlinux/man3p/tmpfile.3p | 152 ++ upstream/archlinux/man3p/tmpnam.3p | 148 ++ upstream/archlinux/man3p/toascii.3p | 66 + upstream/archlinux/man3p/tolower.3p | 102 ++ upstream/archlinux/man3p/toupper.3p | 105 ++ upstream/archlinux/man3p/towctrans.3p | 157 +++ upstream/archlinux/man3p/towlower.3p | 105 ++ upstream/archlinux/man3p/towupper.3p | 105 ++ upstream/archlinux/man3p/trunc.3p | 87 ++ upstream/archlinux/man3p/truncate.3p | 168 +++ upstream/archlinux/man3p/truncf.3p | 42 + upstream/archlinux/man3p/tsearch.3p | 41 + upstream/archlinux/man3p/ttyname.3p | 134 ++ upstream/archlinux/man3p/twalk.3p | 41 + upstream/archlinux/man3p/tzset.3p | 160 +++ upstream/archlinux/man3p/ulimit.3p | 134 ++ upstream/archlinux/man3p/umask.3p | 118 ++ upstream/archlinux/man3p/uname.3p | 124 ++ upstream/archlinux/man3p/ungetc.3p | 120 ++ upstream/archlinux/man3p/ungetwc.3p | 128 ++ upstream/archlinux/man3p/unlink.3p | 455 ++++++ upstream/archlinux/man3p/unlockpt.3p | 87 ++ upstream/archlinux/man3p/unsetenv.3p | 94 ++ upstream/archlinux/man3p/uselocale.3p | 126 ++ upstream/archlinux/man3p/utime.3p | 204 +++ upstream/archlinux/man3p/utimensat.3p | 45 + upstream/archlinux/man3p/va_arg.3p | 46 + upstream/archlinux/man3p/vfprintf.3p | 103 ++ upstream/archlinux/man3p/vfscanf.3p | 96 ++ upstream/archlinux/man3p/vfwprintf.3p | 97 ++ upstream/archlinux/man3p/vfwscanf.3p | 98 ++ upstream/archlinux/man3p/vprintf.3p | 41 + upstream/archlinux/man3p/vscanf.3p | 41 + upstream/archlinux/man3p/vsnprintf.3p | 45 + upstream/archlinux/man3p/vsscanf.3p | 42 + upstream/archlinux/man3p/vswprintf.3p | 43 + upstream/archlinux/man3p/vswscanf.3p | 43 + upstream/archlinux/man3p/vwprintf.3p | 42 + upstream/archlinux/man3p/vwscanf.3p | 42 + upstream/archlinux/man3p/wait.3p | 909 ++++++++++++ upstream/archlinux/man3p/waitid.3p | 269 ++++ upstream/archlinux/man3p/waitpid.3p | 40 + upstream/archlinux/man3p/wcpcpy.3p | 40 + upstream/archlinux/man3p/wcpncpy.3p | 42 + upstream/archlinux/man3p/wcrtomb.3p | 153 ++ upstream/archlinux/man3p/wcscasecmp.3p | 160 +++ upstream/archlinux/man3p/wcscat.3p | 78 + upstream/archlinux/man3p/wcschr.3p | 77 + upstream/archlinux/man3p/wcscmp.3p | 80 ++ upstream/archlinux/man3p/wcscoll.3p | 137 ++ upstream/archlinux/man3p/wcscpy.3p | 101 ++ upstream/archlinux/man3p/wcscspn.3p | 74 + upstream/archlinux/man3p/wcsdup.3p | 93 ++ upstream/archlinux/man3p/wcsftime.3p | 104 ++ upstream/archlinux/man3p/wcslen.3p | 102 ++ upstream/archlinux/man3p/wcsncasecmp.3p | 43 + upstream/archlinux/man3p/wcsncat.3p | 82 ++ upstream/archlinux/man3p/wcsncmp.3p | 83 ++ upstream/archlinux/man3p/wcsncpy.3p | 108 ++ upstream/archlinux/man3p/wcsnlen.3p | 40 + upstream/archlinux/man3p/wcsnrtombs.3p | 41 + upstream/archlinux/man3p/wcspbrk.3p | 75 + upstream/archlinux/man3p/wcsrchr.3p | 78 + upstream/archlinux/man3p/wcsrtombs.3p | 167 +++ upstream/archlinux/man3p/wcsspn.3p | 73 + upstream/archlinux/man3p/wcsstr.3p | 79 ++ upstream/archlinux/man3p/wcstod.3p | 270 ++++ upstream/archlinux/man3p/wcstoimax.3p | 105 ++ upstream/archlinux/man3p/wcstok.3p | 124 ++ upstream/archlinux/man3p/wcstol.3p | 233 +++ upstream/archlinux/man3p/wcstold.3p | 41 + upstream/archlinux/man3p/wcstoll.3p | 41 + upstream/archlinux/man3p/wcstombs.3p | 113 ++ upstream/archlinux/man3p/wcstoul.3p | 235 +++ upstream/archlinux/man3p/wcstoumax.3p | 42 + upstream/archlinux/man3p/wcswidth.3p | 81 ++ upstream/archlinux/man3p/wcsxfrm.3p | 163 +++ upstream/archlinux/man3p/wctob.3p | 82 ++ upstream/archlinux/man3p/wctomb.3p | 129 ++ upstream/archlinux/man3p/wctrans.3p | 141 ++ upstream/archlinux/man3p/wctype.3p | 168 +++ upstream/archlinux/man3p/wcwidth.3p | 78 + upstream/archlinux/man3p/wmemchr.3p | 90 ++ upstream/archlinux/man3p/wmemcmp.3p | 95 ++ upstream/archlinux/man3p/wmemcpy.3p | 90 ++ upstream/archlinux/man3p/wmemmove.3p | 105 ++ upstream/archlinux/man3p/wmemset.3p | 87 ++ upstream/archlinux/man3p/wordexp.3p | 506 +++++++ upstream/archlinux/man3p/wprintf.3p | 41 + upstream/archlinux/man3p/write.3p | 739 ++++++++++ upstream/archlinux/man3p/writev.3p | 171 +++ upstream/archlinux/man3p/wscanf.3p | 41 + upstream/archlinux/man3p/y0.3p | 164 +++ 882 files changed, 132349 insertions(+) create mode 100644 upstream/archlinux/man3p/FD_CLR.3p create mode 100644 upstream/archlinux/man3p/_Exit.3p create mode 100644 upstream/archlinux/man3p/_longjmp.3p create mode 100644 upstream/archlinux/man3p/_tolower.3p create mode 100644 upstream/archlinux/man3p/_toupper.3p create mode 100644 upstream/archlinux/man3p/a64l.3p create mode 100644 upstream/archlinux/man3p/abort.3p create mode 100644 upstream/archlinux/man3p/abs.3p create mode 100644 upstream/archlinux/man3p/accept.3p create mode 100644 upstream/archlinux/man3p/access.3p create mode 100644 upstream/archlinux/man3p/acos.3p create mode 100644 upstream/archlinux/man3p/acosh.3p create mode 100644 upstream/archlinux/man3p/acosl.3p create mode 100644 upstream/archlinux/man3p/aio_cancel.3p create mode 100644 upstream/archlinux/man3p/aio_error.3p create mode 100644 upstream/archlinux/man3p/aio_fsync.3p create mode 100644 upstream/archlinux/man3p/aio_read.3p create mode 100644 upstream/archlinux/man3p/aio_return.3p create mode 100644 upstream/archlinux/man3p/aio_suspend.3p create mode 100644 upstream/archlinux/man3p/aio_write.3p create mode 100644 upstream/archlinux/man3p/alarm.3p create mode 100644 upstream/archlinux/man3p/alphasort.3p create mode 100644 upstream/archlinux/man3p/asctime.3p create mode 100644 upstream/archlinux/man3p/asin.3p create mode 100644 upstream/archlinux/man3p/asinh.3p create mode 100644 upstream/archlinux/man3p/asinl.3p create mode 100644 upstream/archlinux/man3p/assert.3p create mode 100644 upstream/archlinux/man3p/atan.3p create mode 100644 upstream/archlinux/man3p/atan2.3p create mode 100644 upstream/archlinux/man3p/atanf.3p create mode 100644 upstream/archlinux/man3p/atanh.3p create mode 100644 upstream/archlinux/man3p/atanl.3p create mode 100644 upstream/archlinux/man3p/atexit.3p create mode 100644 upstream/archlinux/man3p/atof.3p create mode 100644 upstream/archlinux/man3p/atoi.3p create mode 100644 upstream/archlinux/man3p/atol.3p create mode 100644 upstream/archlinux/man3p/basename.3p create mode 100644 upstream/archlinux/man3p/bind.3p create mode 100644 upstream/archlinux/man3p/bsearch.3p create mode 100644 upstream/archlinux/man3p/btowc.3p create mode 100644 upstream/archlinux/man3p/cabs.3p create mode 100644 upstream/archlinux/man3p/cacos.3p create mode 100644 upstream/archlinux/man3p/cacosh.3p create mode 100644 upstream/archlinux/man3p/cacosl.3p create mode 100644 upstream/archlinux/man3p/calloc.3p create mode 100644 upstream/archlinux/man3p/carg.3p create mode 100644 upstream/archlinux/man3p/casin.3p create mode 100644 upstream/archlinux/man3p/casinh.3p create mode 100644 upstream/archlinux/man3p/casinl.3p create mode 100644 upstream/archlinux/man3p/catan.3p create mode 100644 upstream/archlinux/man3p/catanh.3p create mode 100644 upstream/archlinux/man3p/catanl.3p create mode 100644 upstream/archlinux/man3p/catclose.3p create mode 100644 upstream/archlinux/man3p/catgets.3p create mode 100644 upstream/archlinux/man3p/catopen.3p create mode 100644 upstream/archlinux/man3p/cbrt.3p create mode 100644 upstream/archlinux/man3p/ccos.3p create mode 100644 upstream/archlinux/man3p/ccosh.3p create mode 100644 upstream/archlinux/man3p/ccosl.3p create mode 100644 upstream/archlinux/man3p/ceil.3p create mode 100644 upstream/archlinux/man3p/cexp.3p create mode 100644 upstream/archlinux/man3p/cfgetispeed.3p create mode 100644 upstream/archlinux/man3p/cfgetospeed.3p create mode 100644 upstream/archlinux/man3p/cfsetispeed.3p create mode 100644 upstream/archlinux/man3p/cfsetospeed.3p create mode 100644 upstream/archlinux/man3p/chdir.3p create mode 100644 upstream/archlinux/man3p/chmod.3p create mode 100644 upstream/archlinux/man3p/chown.3p create mode 100644 upstream/archlinux/man3p/cimag.3p create mode 100644 upstream/archlinux/man3p/clearerr.3p create mode 100644 upstream/archlinux/man3p/clock.3p create mode 100644 upstream/archlinux/man3p/clock_getcpuclockid.3p create mode 100644 upstream/archlinux/man3p/clock_getres.3p create mode 100644 upstream/archlinux/man3p/clock_nanosleep.3p create mode 100644 upstream/archlinux/man3p/clock_settime.3p create mode 100644 upstream/archlinux/man3p/clog.3p create mode 100644 upstream/archlinux/man3p/close.3p create mode 100644 upstream/archlinux/man3p/closedir.3p create mode 100644 upstream/archlinux/man3p/closelog.3p create mode 100644 upstream/archlinux/man3p/confstr.3p create mode 100644 upstream/archlinux/man3p/conj.3p create mode 100644 upstream/archlinux/man3p/connect.3p create mode 100644 upstream/archlinux/man3p/copysign.3p create mode 100644 upstream/archlinux/man3p/cos.3p create mode 100644 upstream/archlinux/man3p/cosh.3p create mode 100644 upstream/archlinux/man3p/cosl.3p create mode 100644 upstream/archlinux/man3p/cpow.3p create mode 100644 upstream/archlinux/man3p/cproj.3p create mode 100644 upstream/archlinux/man3p/creal.3p create mode 100644 upstream/archlinux/man3p/creat.3p create mode 100644 upstream/archlinux/man3p/crypt.3p create mode 100644 upstream/archlinux/man3p/csin.3p create mode 100644 upstream/archlinux/man3p/csinh.3p create mode 100644 upstream/archlinux/man3p/csinl.3p create mode 100644 upstream/archlinux/man3p/csqrt.3p create mode 100644 upstream/archlinux/man3p/ctan.3p create mode 100644 upstream/archlinux/man3p/ctanh.3p create mode 100644 upstream/archlinux/man3p/ctanl.3p create mode 100644 upstream/archlinux/man3p/ctermid.3p create mode 100644 upstream/archlinux/man3p/ctime.3p create mode 100644 upstream/archlinux/man3p/daylight.3p create mode 100644 upstream/archlinux/man3p/dbm_clearerr.3p create mode 100644 upstream/archlinux/man3p/difftime.3p create mode 100644 upstream/archlinux/man3p/dirfd.3p create mode 100644 upstream/archlinux/man3p/dirname.3p create mode 100644 upstream/archlinux/man3p/div.3p create mode 100644 upstream/archlinux/man3p/dlclose.3p create mode 100644 upstream/archlinux/man3p/dlerror.3p create mode 100644 upstream/archlinux/man3p/dlopen.3p create mode 100644 upstream/archlinux/man3p/dlsym.3p create mode 100644 upstream/archlinux/man3p/dprintf.3p create mode 100644 upstream/archlinux/man3p/drand48.3p create mode 100644 upstream/archlinux/man3p/dup.3p create mode 100644 upstream/archlinux/man3p/duplocale.3p create mode 100644 upstream/archlinux/man3p/encrypt.3p create mode 100644 upstream/archlinux/man3p/endgrent.3p create mode 100644 upstream/archlinux/man3p/endhostent.3p create mode 100644 upstream/archlinux/man3p/endnetent.3p create mode 100644 upstream/archlinux/man3p/endprotoent.3p create mode 100644 upstream/archlinux/man3p/endpwent.3p create mode 100644 upstream/archlinux/man3p/endservent.3p create mode 100644 upstream/archlinux/man3p/endutxent.3p create mode 100644 upstream/archlinux/man3p/environ.3p create mode 100644 upstream/archlinux/man3p/erand48.3p create mode 100644 upstream/archlinux/man3p/erf.3p create mode 100644 upstream/archlinux/man3p/erfc.3p create mode 100644 upstream/archlinux/man3p/erff.3p create mode 100644 upstream/archlinux/man3p/errno.3p create mode 100644 upstream/archlinux/man3p/exec.3p create mode 100644 upstream/archlinux/man3p/exit.3p create mode 100644 upstream/archlinux/man3p/exp.3p create mode 100644 upstream/archlinux/man3p/exp2.3p create mode 100644 upstream/archlinux/man3p/expm1.3p create mode 100644 upstream/archlinux/man3p/fabs.3p create mode 100644 upstream/archlinux/man3p/faccessat.3p create mode 100644 upstream/archlinux/man3p/fattach.3p create mode 100644 upstream/archlinux/man3p/fchdir.3p create mode 100644 upstream/archlinux/man3p/fchmod.3p create mode 100644 upstream/archlinux/man3p/fchmodat.3p create mode 100644 upstream/archlinux/man3p/fchown.3p create mode 100644 upstream/archlinux/man3p/fchownat.3p create mode 100644 upstream/archlinux/man3p/fclose.3p create mode 100644 upstream/archlinux/man3p/fcntl.3p create mode 100644 upstream/archlinux/man3p/fdatasync.3p create mode 100644 upstream/archlinux/man3p/fdetach.3p create mode 100644 upstream/archlinux/man3p/fdim.3p create mode 100644 upstream/archlinux/man3p/fdopen.3p create mode 100644 upstream/archlinux/man3p/fdopendir.3p create mode 100644 upstream/archlinux/man3p/feclearexcept.3p create mode 100644 upstream/archlinux/man3p/fegetenv.3p create mode 100644 upstream/archlinux/man3p/fegetexceptflag.3p create mode 100644 upstream/archlinux/man3p/fegetround.3p create mode 100644 upstream/archlinux/man3p/feholdexcept.3p create mode 100644 upstream/archlinux/man3p/feof.3p create mode 100644 upstream/archlinux/man3p/feraiseexcept.3p create mode 100644 upstream/archlinux/man3p/ferror.3p create mode 100644 upstream/archlinux/man3p/fesetenv.3p create mode 100644 upstream/archlinux/man3p/fesetexceptflag.3p create mode 100644 upstream/archlinux/man3p/fesetround.3p create mode 100644 upstream/archlinux/man3p/fetestexcept.3p create mode 100644 upstream/archlinux/man3p/feupdateenv.3p create mode 100644 upstream/archlinux/man3p/fexecve.3p create mode 100644 upstream/archlinux/man3p/fflush.3p create mode 100644 upstream/archlinux/man3p/ffs.3p create mode 100644 upstream/archlinux/man3p/fgetc.3p create mode 100644 upstream/archlinux/man3p/fgetpos.3p create mode 100644 upstream/archlinux/man3p/fgets.3p create mode 100644 upstream/archlinux/man3p/fgetwc.3p create mode 100644 upstream/archlinux/man3p/fgetws.3p create mode 100644 upstream/archlinux/man3p/fileno.3p create mode 100644 upstream/archlinux/man3p/flockfile.3p create mode 100644 upstream/archlinux/man3p/floor.3p create mode 100644 upstream/archlinux/man3p/fma.3p create mode 100644 upstream/archlinux/man3p/fmax.3p create mode 100644 upstream/archlinux/man3p/fmemopen.3p create mode 100644 upstream/archlinux/man3p/fmin.3p create mode 100644 upstream/archlinux/man3p/fmod.3p create mode 100644 upstream/archlinux/man3p/fmtmsg.3p create mode 100644 upstream/archlinux/man3p/fnmatch.3p create mode 100644 upstream/archlinux/man3p/fopen.3p create mode 100644 upstream/archlinux/man3p/fork.3p create mode 100644 upstream/archlinux/man3p/fpathconf.3p create mode 100644 upstream/archlinux/man3p/fpclassify.3p create mode 100644 upstream/archlinux/man3p/fprintf.3p create mode 100644 upstream/archlinux/man3p/fputc.3p create mode 100644 upstream/archlinux/man3p/fputs.3p create mode 100644 upstream/archlinux/man3p/fputwc.3p create mode 100644 upstream/archlinux/man3p/fputws.3p create mode 100644 upstream/archlinux/man3p/fread.3p create mode 100644 upstream/archlinux/man3p/free.3p create mode 100644 upstream/archlinux/man3p/freeaddrinfo.3p create mode 100644 upstream/archlinux/man3p/freelocale.3p create mode 100644 upstream/archlinux/man3p/freopen.3p create mode 100644 upstream/archlinux/man3p/frexp.3p create mode 100644 upstream/archlinux/man3p/fscanf.3p create mode 100644 upstream/archlinux/man3p/fseek.3p create mode 100644 upstream/archlinux/man3p/fsetpos.3p create mode 100644 upstream/archlinux/man3p/fstat.3p create mode 100644 upstream/archlinux/man3p/fstatat.3p create mode 100644 upstream/archlinux/man3p/fstatvfs.3p create mode 100644 upstream/archlinux/man3p/fsync.3p create mode 100644 upstream/archlinux/man3p/ftell.3p create mode 100644 upstream/archlinux/man3p/ftok.3p create mode 100644 upstream/archlinux/man3p/ftruncate.3p create mode 100644 upstream/archlinux/man3p/ftrylockfile.3p create mode 100644 upstream/archlinux/man3p/ftw.3p create mode 100644 upstream/archlinux/man3p/funlockfile.3p create mode 100644 upstream/archlinux/man3p/futimens.3p create mode 100644 upstream/archlinux/man3p/fwide.3p create mode 100644 upstream/archlinux/man3p/fwprintf.3p create mode 100644 upstream/archlinux/man3p/fwrite.3p create mode 100644 upstream/archlinux/man3p/fwscanf.3p create mode 100644 upstream/archlinux/man3p/gai_strerror.3p create mode 100644 upstream/archlinux/man3p/getaddrinfo.3p create mode 100644 upstream/archlinux/man3p/getc.3p create mode 100644 upstream/archlinux/man3p/getc_unlocked.3p create mode 100644 upstream/archlinux/man3p/getchar.3p create mode 100644 upstream/archlinux/man3p/getchar_unlocked.3p create mode 100644 upstream/archlinux/man3p/getcwd.3p create mode 100644 upstream/archlinux/man3p/getdate.3p create mode 100644 upstream/archlinux/man3p/getdelim.3p create mode 100644 upstream/archlinux/man3p/getegid.3p create mode 100644 upstream/archlinux/man3p/getenv.3p create mode 100644 upstream/archlinux/man3p/geteuid.3p create mode 100644 upstream/archlinux/man3p/getgid.3p create mode 100644 upstream/archlinux/man3p/getgrent.3p create mode 100644 upstream/archlinux/man3p/getgrgid.3p create mode 100644 upstream/archlinux/man3p/getgrnam.3p create mode 100644 upstream/archlinux/man3p/getgroups.3p create mode 100644 upstream/archlinux/man3p/gethostent.3p create mode 100644 upstream/archlinux/man3p/gethostid.3p create mode 100644 upstream/archlinux/man3p/gethostname.3p create mode 100644 upstream/archlinux/man3p/getitimer.3p create mode 100644 upstream/archlinux/man3p/getline.3p create mode 100644 upstream/archlinux/man3p/getlogin.3p create mode 100644 upstream/archlinux/man3p/getmsg.3p create mode 100644 upstream/archlinux/man3p/getnameinfo.3p create mode 100644 upstream/archlinux/man3p/getnetbyaddr.3p create mode 100644 upstream/archlinux/man3p/getopt.3p create mode 100644 upstream/archlinux/man3p/getpeername.3p create mode 100644 upstream/archlinux/man3p/getpgid.3p create mode 100644 upstream/archlinux/man3p/getpgrp.3p create mode 100644 upstream/archlinux/man3p/getpid.3p create mode 100644 upstream/archlinux/man3p/getpmsg.3p create mode 100644 upstream/archlinux/man3p/getppid.3p create mode 100644 upstream/archlinux/man3p/getpriority.3p create mode 100644 upstream/archlinux/man3p/getprotobyname.3p create mode 100644 upstream/archlinux/man3p/getpwent.3p create mode 100644 upstream/archlinux/man3p/getpwnam.3p create mode 100644 upstream/archlinux/man3p/getpwuid.3p create mode 100644 upstream/archlinux/man3p/getrlimit.3p create mode 100644 upstream/archlinux/man3p/getrusage.3p create mode 100644 upstream/archlinux/man3p/gets.3p create mode 100644 upstream/archlinux/man3p/getservbyname.3p create mode 100644 upstream/archlinux/man3p/getsid.3p create mode 100644 upstream/archlinux/man3p/getsockname.3p create mode 100644 upstream/archlinux/man3p/getsockopt.3p create mode 100644 upstream/archlinux/man3p/getsubopt.3p create mode 100644 upstream/archlinux/man3p/gettimeofday.3p create mode 100644 upstream/archlinux/man3p/getuid.3p create mode 100644 upstream/archlinux/man3p/getutxent.3p create mode 100644 upstream/archlinux/man3p/getwc.3p create mode 100644 upstream/archlinux/man3p/getwchar.3p create mode 100644 upstream/archlinux/man3p/glob.3p create mode 100644 upstream/archlinux/man3p/gmtime.3p create mode 100644 upstream/archlinux/man3p/grantpt.3p create mode 100644 upstream/archlinux/man3p/hcreate.3p create mode 100644 upstream/archlinux/man3p/htonl.3p create mode 100644 upstream/archlinux/man3p/hypot.3p create mode 100644 upstream/archlinux/man3p/iconv.3p create mode 100644 upstream/archlinux/man3p/iconv_close.3p create mode 100644 upstream/archlinux/man3p/iconv_open.3p create mode 100644 upstream/archlinux/man3p/if_freenameindex.3p create mode 100644 upstream/archlinux/man3p/if_indextoname.3p create mode 100644 upstream/archlinux/man3p/if_nameindex.3p create mode 100644 upstream/archlinux/man3p/if_nametoindex.3p create mode 100644 upstream/archlinux/man3p/ilogb.3p create mode 100644 upstream/archlinux/man3p/imaxabs.3p create mode 100644 upstream/archlinux/man3p/imaxdiv.3p create mode 100644 upstream/archlinux/man3p/inet_addr.3p create mode 100644 upstream/archlinux/man3p/inet_ntop.3p create mode 100644 upstream/archlinux/man3p/initstate.3p create mode 100644 upstream/archlinux/man3p/insque.3p create mode 100644 upstream/archlinux/man3p/ioctl.3p create mode 100644 upstream/archlinux/man3p/isalnum.3p create mode 100644 upstream/archlinux/man3p/isalpha.3p create mode 100644 upstream/archlinux/man3p/isascii.3p create mode 100644 upstream/archlinux/man3p/isastream.3p create mode 100644 upstream/archlinux/man3p/isatty.3p create mode 100644 upstream/archlinux/man3p/isblank.3p create mode 100644 upstream/archlinux/man3p/iscntrl.3p create mode 100644 upstream/archlinux/man3p/isdigit.3p create mode 100644 upstream/archlinux/man3p/isfinite.3p create mode 100644 upstream/archlinux/man3p/isgraph.3p create mode 100644 upstream/archlinux/man3p/isgreater.3p create mode 100644 upstream/archlinux/man3p/isgreaterequal.3p create mode 100644 upstream/archlinux/man3p/isinf.3p create mode 100644 upstream/archlinux/man3p/isless.3p create mode 100644 upstream/archlinux/man3p/islessequal.3p create mode 100644 upstream/archlinux/man3p/islessgreater.3p create mode 100644 upstream/archlinux/man3p/islower.3p create mode 100644 upstream/archlinux/man3p/isnan.3p create mode 100644 upstream/archlinux/man3p/isnormal.3p create mode 100644 upstream/archlinux/man3p/isprint.3p create mode 100644 upstream/archlinux/man3p/ispunct.3p create mode 100644 upstream/archlinux/man3p/isspace.3p create mode 100644 upstream/archlinux/man3p/isunordered.3p create mode 100644 upstream/archlinux/man3p/isupper.3p create mode 100644 upstream/archlinux/man3p/iswalnum.3p create mode 100644 upstream/archlinux/man3p/iswalpha.3p create mode 100644 upstream/archlinux/man3p/iswblank.3p create mode 100644 upstream/archlinux/man3p/iswcntrl.3p create mode 100644 upstream/archlinux/man3p/iswctype.3p create mode 100644 upstream/archlinux/man3p/iswdigit.3p create mode 100644 upstream/archlinux/man3p/iswgraph.3p create mode 100644 upstream/archlinux/man3p/iswlower.3p create mode 100644 upstream/archlinux/man3p/iswprint.3p create mode 100644 upstream/archlinux/man3p/iswpunct.3p create mode 100644 upstream/archlinux/man3p/iswspace.3p create mode 100644 upstream/archlinux/man3p/iswupper.3p create mode 100644 upstream/archlinux/man3p/iswxdigit.3p create mode 100644 upstream/archlinux/man3p/isxdigit.3p create mode 100644 upstream/archlinux/man3p/j0.3p create mode 100644 upstream/archlinux/man3p/jrand48.3p create mode 100644 upstream/archlinux/man3p/kill.3p create mode 100644 upstream/archlinux/man3p/killpg.3p create mode 100644 upstream/archlinux/man3p/l64a.3p create mode 100644 upstream/archlinux/man3p/labs.3p create mode 100644 upstream/archlinux/man3p/lchown.3p create mode 100644 upstream/archlinux/man3p/lcong48.3p create mode 100644 upstream/archlinux/man3p/ldexp.3p create mode 100644 upstream/archlinux/man3p/ldiv.3p create mode 100644 upstream/archlinux/man3p/lfind.3p create mode 100644 upstream/archlinux/man3p/lgamma.3p create mode 100644 upstream/archlinux/man3p/link.3p create mode 100644 upstream/archlinux/man3p/lio_listio.3p create mode 100644 upstream/archlinux/man3p/listen.3p create mode 100644 upstream/archlinux/man3p/llabs.3p create mode 100644 upstream/archlinux/man3p/lldiv.3p create mode 100644 upstream/archlinux/man3p/llrint.3p create mode 100644 upstream/archlinux/man3p/llround.3p create mode 100644 upstream/archlinux/man3p/localeconv.3p create mode 100644 upstream/archlinux/man3p/localtime.3p create mode 100644 upstream/archlinux/man3p/lockf.3p create mode 100644 upstream/archlinux/man3p/log.3p create mode 100644 upstream/archlinux/man3p/log10.3p create mode 100644 upstream/archlinux/man3p/log1p.3p create mode 100644 upstream/archlinux/man3p/log2.3p create mode 100644 upstream/archlinux/man3p/logb.3p create mode 100644 upstream/archlinux/man3p/logf.3p create mode 100644 upstream/archlinux/man3p/longjmp.3p create mode 100644 upstream/archlinux/man3p/lrand48.3p create mode 100644 upstream/archlinux/man3p/lrint.3p create mode 100644 upstream/archlinux/man3p/lround.3p create mode 100644 upstream/archlinux/man3p/lsearch.3p create mode 100644 upstream/archlinux/man3p/lseek.3p create mode 100644 upstream/archlinux/man3p/lstat.3p create mode 100644 upstream/archlinux/man3p/malloc.3p create mode 100644 upstream/archlinux/man3p/mblen.3p create mode 100644 upstream/archlinux/man3p/mbrlen.3p create mode 100644 upstream/archlinux/man3p/mbrtowc.3p create mode 100644 upstream/archlinux/man3p/mbsinit.3p create mode 100644 upstream/archlinux/man3p/mbsrtowcs.3p create mode 100644 upstream/archlinux/man3p/mbstowcs.3p create mode 100644 upstream/archlinux/man3p/mbtowc.3p create mode 100644 upstream/archlinux/man3p/memccpy.3p create mode 100644 upstream/archlinux/man3p/memchr.3p create mode 100644 upstream/archlinux/man3p/memcmp.3p create mode 100644 upstream/archlinux/man3p/memcpy.3p create mode 100644 upstream/archlinux/man3p/memmove.3p create mode 100644 upstream/archlinux/man3p/memset.3p create mode 100644 upstream/archlinux/man3p/mkdir.3p create mode 100644 upstream/archlinux/man3p/mkdtemp.3p create mode 100644 upstream/archlinux/man3p/mkfifo.3p create mode 100644 upstream/archlinux/man3p/mknod.3p create mode 100644 upstream/archlinux/man3p/mkstemp.3p create mode 100644 upstream/archlinux/man3p/mktime.3p create mode 100644 upstream/archlinux/man3p/mlock.3p create mode 100644 upstream/archlinux/man3p/mlockall.3p create mode 100644 upstream/archlinux/man3p/mmap.3p create mode 100644 upstream/archlinux/man3p/modf.3p create mode 100644 upstream/archlinux/man3p/mprotect.3p create mode 100644 upstream/archlinux/man3p/mq_close.3p create mode 100644 upstream/archlinux/man3p/mq_getattr.3p create mode 100644 upstream/archlinux/man3p/mq_notify.3p create mode 100644 upstream/archlinux/man3p/mq_open.3p create mode 100644 upstream/archlinux/man3p/mq_receive.3p create mode 100644 upstream/archlinux/man3p/mq_send.3p create mode 100644 upstream/archlinux/man3p/mq_setattr.3p create mode 100644 upstream/archlinux/man3p/mq_timedreceive.3p create mode 100644 upstream/archlinux/man3p/mq_timedsend.3p create mode 100644 upstream/archlinux/man3p/mq_unlink.3p create mode 100644 upstream/archlinux/man3p/mrand48.3p create mode 100644 upstream/archlinux/man3p/msgctl.3p create mode 100644 upstream/archlinux/man3p/msgget.3p create mode 100644 upstream/archlinux/man3p/msgrcv.3p create mode 100644 upstream/archlinux/man3p/msgsnd.3p create mode 100644 upstream/archlinux/man3p/msync.3p create mode 100644 upstream/archlinux/man3p/munlock.3p create mode 100644 upstream/archlinux/man3p/munlockall.3p create mode 100644 upstream/archlinux/man3p/munmap.3p create mode 100644 upstream/archlinux/man3p/nan.3p create mode 100644 upstream/archlinux/man3p/nanosleep.3p create mode 100644 upstream/archlinux/man3p/nearbyint.3p create mode 100644 upstream/archlinux/man3p/newlocale.3p create mode 100644 upstream/archlinux/man3p/nextafter.3p create mode 100644 upstream/archlinux/man3p/nftw.3p create mode 100644 upstream/archlinux/man3p/nice.3p create mode 100644 upstream/archlinux/man3p/nl_langinfo.3p create mode 100644 upstream/archlinux/man3p/nrand48.3p create mode 100644 upstream/archlinux/man3p/ntohl.3p create mode 100644 upstream/archlinux/man3p/open.3p create mode 100644 upstream/archlinux/man3p/open_memstream.3p create mode 100644 upstream/archlinux/man3p/openat.3p create mode 100644 upstream/archlinux/man3p/opendir.3p create mode 100644 upstream/archlinux/man3p/openlog.3p create mode 100644 upstream/archlinux/man3p/optarg.3p create mode 100644 upstream/archlinux/man3p/pathconf.3p create mode 100644 upstream/archlinux/man3p/pause.3p create mode 100644 upstream/archlinux/man3p/pclose.3p create mode 100644 upstream/archlinux/man3p/perror.3p create mode 100644 upstream/archlinux/man3p/pipe.3p create mode 100644 upstream/archlinux/man3p/poll.3p create mode 100644 upstream/archlinux/man3p/popen.3p create mode 100644 upstream/archlinux/man3p/posix_fadvise.3p create mode 100644 upstream/archlinux/man3p/posix_fallocate.3p create mode 100644 upstream/archlinux/man3p/posix_madvise.3p create mode 100644 upstream/archlinux/man3p/posix_mem_offset.3p create mode 100644 upstream/archlinux/man3p/posix_memalign.3p create mode 100644 upstream/archlinux/man3p/posix_openpt.3p create mode 100644 upstream/archlinux/man3p/posix_spawn.3p create mode 100644 upstream/archlinux/man3p/posix_spawn_file_actions_addclose.3p create mode 100644 upstream/archlinux/man3p/posix_spawn_file_actions_adddup2.3p create mode 100644 upstream/archlinux/man3p/posix_spawn_file_actions_addopen.3p create mode 100644 upstream/archlinux/man3p/posix_spawn_file_actions_destroy.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_destroy.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_getflags.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_getpgroup.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_getschedparam.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_getschedpolicy.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_getsigdefault.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_getsigmask.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_init.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_setflags.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_setpgroup.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_setschedparam.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_setschedpolicy.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_setsigdefault.3p create mode 100644 upstream/archlinux/man3p/posix_spawnattr_setsigmask.3p create mode 100644 upstream/archlinux/man3p/posix_spawnp.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_destroy.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_getclockres.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_getinherited.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_getlogsize.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_getname.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_getstreamfullpolicy.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_getstreamsize.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_init.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_setinherited.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_setlogsize.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_setname.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_setstreamfullpolicy.3p create mode 100644 upstream/archlinux/man3p/posix_trace_attr_setstreamsize.3p create mode 100644 upstream/archlinux/man3p/posix_trace_clear.3p create mode 100644 upstream/archlinux/man3p/posix_trace_close.3p create mode 100644 upstream/archlinux/man3p/posix_trace_create.3p create mode 100644 upstream/archlinux/man3p/posix_trace_event.3p create mode 100644 upstream/archlinux/man3p/posix_trace_eventid_equal.3p create mode 100644 upstream/archlinux/man3p/posix_trace_eventid_open.3p create mode 100644 upstream/archlinux/man3p/posix_trace_eventset_add.3p create mode 100644 upstream/archlinux/man3p/posix_trace_eventtypelist_getnext_id.3p create mode 100644 upstream/archlinux/man3p/posix_trace_flush.3p create mode 100644 upstream/archlinux/man3p/posix_trace_get_attr.3p create mode 100644 upstream/archlinux/man3p/posix_trace_get_filter.3p create mode 100644 upstream/archlinux/man3p/posix_trace_get_status.3p create mode 100644 upstream/archlinux/man3p/posix_trace_getnext_event.3p create mode 100644 upstream/archlinux/man3p/posix_trace_open.3p create mode 100644 upstream/archlinux/man3p/posix_trace_set_filter.3p create mode 100644 upstream/archlinux/man3p/posix_trace_shutdown.3p create mode 100644 upstream/archlinux/man3p/posix_trace_start.3p create mode 100644 upstream/archlinux/man3p/posix_trace_timedgetnext_event.3p create mode 100644 upstream/archlinux/man3p/posix_trace_trid_eventid_open.3p create mode 100644 upstream/archlinux/man3p/posix_trace_trygetnext_event.3p create mode 100644 upstream/archlinux/man3p/posix_typed_mem_get_info.3p create mode 100644 upstream/archlinux/man3p/posix_typed_mem_open.3p create mode 100644 upstream/archlinux/man3p/pow.3p create mode 100644 upstream/archlinux/man3p/pread.3p create mode 100644 upstream/archlinux/man3p/printf.3p create mode 100644 upstream/archlinux/man3p/pselect.3p create mode 100644 upstream/archlinux/man3p/psiginfo.3p create mode 100644 upstream/archlinux/man3p/pthread_atfork.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getdetachstate.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getguardsize.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getinheritsched.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getschedparam.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getschedpolicy.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getscope.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getstack.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_getstacksize.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_init.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setdetachstate.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setguardsize.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setinheritsched.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setschedparam.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setschedpolicy.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setscope.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setstack.3p create mode 100644 upstream/archlinux/man3p/pthread_attr_setstacksize.3p create mode 100644 upstream/archlinux/man3p/pthread_barrier_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_barrier_wait.3p create mode 100644 upstream/archlinux/man3p/pthread_barrierattr_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_barrierattr_getpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_barrierattr_init.3p create mode 100644 upstream/archlinux/man3p/pthread_barrierattr_setpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_cancel.3p create mode 100644 upstream/archlinux/man3p/pthread_cleanup_pop.3p create mode 100644 upstream/archlinux/man3p/pthread_cond_broadcast.3p create mode 100644 upstream/archlinux/man3p/pthread_cond_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_cond_signal.3p create mode 100644 upstream/archlinux/man3p/pthread_cond_timedwait.3p create mode 100644 upstream/archlinux/man3p/pthread_condattr_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_condattr_getclock.3p create mode 100644 upstream/archlinux/man3p/pthread_condattr_getpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_condattr_init.3p create mode 100644 upstream/archlinux/man3p/pthread_condattr_setclock.3p create mode 100644 upstream/archlinux/man3p/pthread_condattr_setpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_create.3p create mode 100644 upstream/archlinux/man3p/pthread_detach.3p create mode 100644 upstream/archlinux/man3p/pthread_equal.3p create mode 100644 upstream/archlinux/man3p/pthread_exit.3p create mode 100644 upstream/archlinux/man3p/pthread_getconcurrency.3p create mode 100644 upstream/archlinux/man3p/pthread_getcpuclockid.3p create mode 100644 upstream/archlinux/man3p/pthread_getschedparam.3p create mode 100644 upstream/archlinux/man3p/pthread_getspecific.3p create mode 100644 upstream/archlinux/man3p/pthread_join.3p create mode 100644 upstream/archlinux/man3p/pthread_key_create.3p create mode 100644 upstream/archlinux/man3p/pthread_key_delete.3p create mode 100644 upstream/archlinux/man3p/pthread_kill.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_consistent.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_getprioceiling.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_init.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_lock.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_setprioceiling.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_timedlock.3p create mode 100644 upstream/archlinux/man3p/pthread_mutex_trylock.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_getprioceiling.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_getprotocol.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_getpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_getrobust.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_gettype.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_init.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_setprioceiling.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_setprotocol.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_setpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_setrobust.3p create mode 100644 upstream/archlinux/man3p/pthread_mutexattr_settype.3p create mode 100644 upstream/archlinux/man3p/pthread_once.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_rdlock.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_timedrdlock.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_timedwrlock.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_tryrdlock.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_trywrlock.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_unlock.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlock_wrlock.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlockattr_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlockattr_getpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlockattr_init.3p create mode 100644 upstream/archlinux/man3p/pthread_rwlockattr_setpshared.3p create mode 100644 upstream/archlinux/man3p/pthread_self.3p create mode 100644 upstream/archlinux/man3p/pthread_setcancelstate.3p create mode 100644 upstream/archlinux/man3p/pthread_setconcurrency.3p create mode 100644 upstream/archlinux/man3p/pthread_setschedparam.3p create mode 100644 upstream/archlinux/man3p/pthread_setschedprio.3p create mode 100644 upstream/archlinux/man3p/pthread_setspecific.3p create mode 100644 upstream/archlinux/man3p/pthread_sigmask.3p create mode 100644 upstream/archlinux/man3p/pthread_spin_destroy.3p create mode 100644 upstream/archlinux/man3p/pthread_spin_lock.3p create mode 100644 upstream/archlinux/man3p/pthread_spin_unlock.3p create mode 100644 upstream/archlinux/man3p/pthread_testcancel.3p create mode 100644 upstream/archlinux/man3p/ptsname.3p create mode 100644 upstream/archlinux/man3p/putc.3p create mode 100644 upstream/archlinux/man3p/putc_unlocked.3p create mode 100644 upstream/archlinux/man3p/putchar.3p create mode 100644 upstream/archlinux/man3p/putchar_unlocked.3p create mode 100644 upstream/archlinux/man3p/putenv.3p create mode 100644 upstream/archlinux/man3p/putmsg.3p create mode 100644 upstream/archlinux/man3p/puts.3p create mode 100644 upstream/archlinux/man3p/pututxline.3p create mode 100644 upstream/archlinux/man3p/putwc.3p create mode 100644 upstream/archlinux/man3p/putwchar.3p create mode 100644 upstream/archlinux/man3p/pwrite.3p create mode 100644 upstream/archlinux/man3p/qsort.3p create mode 100644 upstream/archlinux/man3p/raise.3p create mode 100644 upstream/archlinux/man3p/rand.3p create mode 100644 upstream/archlinux/man3p/random.3p create mode 100644 upstream/archlinux/man3p/read.3p create mode 100644 upstream/archlinux/man3p/readdir.3p create mode 100644 upstream/archlinux/man3p/readlink.3p create mode 100644 upstream/archlinux/man3p/readv.3p create mode 100644 upstream/archlinux/man3p/realloc.3p create mode 100644 upstream/archlinux/man3p/realpath.3p create mode 100644 upstream/archlinux/man3p/recv.3p create mode 100644 upstream/archlinux/man3p/recvfrom.3p create mode 100644 upstream/archlinux/man3p/recvmsg.3p create mode 100644 upstream/archlinux/man3p/regcomp.3p create mode 100644 upstream/archlinux/man3p/remainder.3p create mode 100644 upstream/archlinux/man3p/remove.3p create mode 100644 upstream/archlinux/man3p/remque.3p create mode 100644 upstream/archlinux/man3p/remquo.3p create mode 100644 upstream/archlinux/man3p/rename.3p create mode 100644 upstream/archlinux/man3p/rewind.3p create mode 100644 upstream/archlinux/man3p/rewinddir.3p create mode 100644 upstream/archlinux/man3p/rint.3p create mode 100644 upstream/archlinux/man3p/rmdir.3p create mode 100644 upstream/archlinux/man3p/round.3p create mode 100644 upstream/archlinux/man3p/scalbln.3p create mode 100644 upstream/archlinux/man3p/scandir.3p create mode 100644 upstream/archlinux/man3p/scanf.3p create mode 100644 upstream/archlinux/man3p/sched_get_priority_max.3p create mode 100644 upstream/archlinux/man3p/sched_getparam.3p create mode 100644 upstream/archlinux/man3p/sched_getscheduler.3p create mode 100644 upstream/archlinux/man3p/sched_rr_get_interval.3p create mode 100644 upstream/archlinux/man3p/sched_setparam.3p create mode 100644 upstream/archlinux/man3p/sched_setscheduler.3p create mode 100644 upstream/archlinux/man3p/sched_yield.3p create mode 100644 upstream/archlinux/man3p/seed48.3p create mode 100644 upstream/archlinux/man3p/seekdir.3p create mode 100644 upstream/archlinux/man3p/select.3p create mode 100644 upstream/archlinux/man3p/sem_close.3p create mode 100644 upstream/archlinux/man3p/sem_destroy.3p create mode 100644 upstream/archlinux/man3p/sem_getvalue.3p create mode 100644 upstream/archlinux/man3p/sem_init.3p create mode 100644 upstream/archlinux/man3p/sem_open.3p create mode 100644 upstream/archlinux/man3p/sem_post.3p create mode 100644 upstream/archlinux/man3p/sem_timedwait.3p create mode 100644 upstream/archlinux/man3p/sem_trywait.3p create mode 100644 upstream/archlinux/man3p/sem_unlink.3p create mode 100644 upstream/archlinux/man3p/sem_wait.3p create mode 100644 upstream/archlinux/man3p/semctl.3p create mode 100644 upstream/archlinux/man3p/semget.3p create mode 100644 upstream/archlinux/man3p/semop.3p create mode 100644 upstream/archlinux/man3p/send.3p create mode 100644 upstream/archlinux/man3p/sendmsg.3p create mode 100644 upstream/archlinux/man3p/sendto.3p create mode 100644 upstream/archlinux/man3p/setbuf.3p create mode 100644 upstream/archlinux/man3p/setegid.3p create mode 100644 upstream/archlinux/man3p/setenv.3p create mode 100644 upstream/archlinux/man3p/seteuid.3p create mode 100644 upstream/archlinux/man3p/setgid.3p create mode 100644 upstream/archlinux/man3p/setgrent.3p create mode 100644 upstream/archlinux/man3p/sethostent.3p create mode 100644 upstream/archlinux/man3p/setitimer.3p create mode 100644 upstream/archlinux/man3p/setjmp.3p create mode 100644 upstream/archlinux/man3p/setkey.3p create mode 100644 upstream/archlinux/man3p/setlocale.3p create mode 100644 upstream/archlinux/man3p/setlogmask.3p create mode 100644 upstream/archlinux/man3p/setnetent.3p create mode 100644 upstream/archlinux/man3p/setpgid.3p create mode 100644 upstream/archlinux/man3p/setpgrp.3p create mode 100644 upstream/archlinux/man3p/setpriority.3p create mode 100644 upstream/archlinux/man3p/setprotoent.3p create mode 100644 upstream/archlinux/man3p/setpwent.3p create mode 100644 upstream/archlinux/man3p/setregid.3p create mode 100644 upstream/archlinux/man3p/setreuid.3p create mode 100644 upstream/archlinux/man3p/setrlimit.3p create mode 100644 upstream/archlinux/man3p/setservent.3p create mode 100644 upstream/archlinux/man3p/setsid.3p create mode 100644 upstream/archlinux/man3p/setsockopt.3p create mode 100644 upstream/archlinux/man3p/setstate.3p create mode 100644 upstream/archlinux/man3p/setuid.3p create mode 100644 upstream/archlinux/man3p/setutxent.3p create mode 100644 upstream/archlinux/man3p/setvbuf.3p create mode 100644 upstream/archlinux/man3p/shm_open.3p create mode 100644 upstream/archlinux/man3p/shm_unlink.3p create mode 100644 upstream/archlinux/man3p/shmat.3p create mode 100644 upstream/archlinux/man3p/shmctl.3p create mode 100644 upstream/archlinux/man3p/shmdt.3p create mode 100644 upstream/archlinux/man3p/shmget.3p create mode 100644 upstream/archlinux/man3p/shutdown.3p create mode 100644 upstream/archlinux/man3p/sigaction.3p create mode 100644 upstream/archlinux/man3p/sigaddset.3p create mode 100644 upstream/archlinux/man3p/sigaltstack.3p create mode 100644 upstream/archlinux/man3p/sigdelset.3p create mode 100644 upstream/archlinux/man3p/sigemptyset.3p create mode 100644 upstream/archlinux/man3p/sigfillset.3p create mode 100644 upstream/archlinux/man3p/sighold.3p create mode 100644 upstream/archlinux/man3p/siginterrupt.3p create mode 100644 upstream/archlinux/man3p/sigismember.3p create mode 100644 upstream/archlinux/man3p/siglongjmp.3p create mode 100644 upstream/archlinux/man3p/signal.3p create mode 100644 upstream/archlinux/man3p/signbit.3p create mode 100644 upstream/archlinux/man3p/signgam.3p create mode 100644 upstream/archlinux/man3p/sigpause.3p create mode 100644 upstream/archlinux/man3p/sigpending.3p create mode 100644 upstream/archlinux/man3p/sigprocmask.3p create mode 100644 upstream/archlinux/man3p/sigqueue.3p create mode 100644 upstream/archlinux/man3p/sigrelse.3p create mode 100644 upstream/archlinux/man3p/sigsetjmp.3p create mode 100644 upstream/archlinux/man3p/sigsuspend.3p create mode 100644 upstream/archlinux/man3p/sigtimedwait.3p create mode 100644 upstream/archlinux/man3p/sigwait.3p create mode 100644 upstream/archlinux/man3p/sigwaitinfo.3p create mode 100644 upstream/archlinux/man3p/sin.3p create mode 100644 upstream/archlinux/man3p/sinh.3p create mode 100644 upstream/archlinux/man3p/sinl.3p create mode 100644 upstream/archlinux/man3p/sleep.3p create mode 100644 upstream/archlinux/man3p/snprintf.3p create mode 100644 upstream/archlinux/man3p/sockatmark.3p create mode 100644 upstream/archlinux/man3p/socket.3p create mode 100644 upstream/archlinux/man3p/socketpair.3p create mode 100644 upstream/archlinux/man3p/sprintf.3p create mode 100644 upstream/archlinux/man3p/sqrt.3p create mode 100644 upstream/archlinux/man3p/srand.3p create mode 100644 upstream/archlinux/man3p/srand48.3p create mode 100644 upstream/archlinux/man3p/srandom.3p create mode 100644 upstream/archlinux/man3p/sscanf.3p create mode 100644 upstream/archlinux/man3p/stat.3p create mode 100644 upstream/archlinux/man3p/statvfs.3p create mode 100644 upstream/archlinux/man3p/stdin.3p create mode 100644 upstream/archlinux/man3p/stpcpy.3p create mode 100644 upstream/archlinux/man3p/stpncpy.3p create mode 100644 upstream/archlinux/man3p/strcasecmp.3p create mode 100644 upstream/archlinux/man3p/strcat.3p create mode 100644 upstream/archlinux/man3p/strchr.3p create mode 100644 upstream/archlinux/man3p/strcmp.3p create mode 100644 upstream/archlinux/man3p/strcoll.3p create mode 100644 upstream/archlinux/man3p/strcpy.3p create mode 100644 upstream/archlinux/man3p/strcspn.3p create mode 100644 upstream/archlinux/man3p/strdup.3p create mode 100644 upstream/archlinux/man3p/strerror.3p create mode 100644 upstream/archlinux/man3p/strfmon.3p create mode 100644 upstream/archlinux/man3p/strftime.3p create mode 100644 upstream/archlinux/man3p/strlen.3p create mode 100644 upstream/archlinux/man3p/strncasecmp.3p create mode 100644 upstream/archlinux/man3p/strncat.3p create mode 100644 upstream/archlinux/man3p/strncmp.3p create mode 100644 upstream/archlinux/man3p/strncpy.3p create mode 100644 upstream/archlinux/man3p/strndup.3p create mode 100644 upstream/archlinux/man3p/strnlen.3p create mode 100644 upstream/archlinux/man3p/strpbrk.3p create mode 100644 upstream/archlinux/man3p/strptime.3p create mode 100644 upstream/archlinux/man3p/strrchr.3p create mode 100644 upstream/archlinux/man3p/strsignal.3p create mode 100644 upstream/archlinux/man3p/strspn.3p create mode 100644 upstream/archlinux/man3p/strstr.3p create mode 100644 upstream/archlinux/man3p/strtod.3p create mode 100644 upstream/archlinux/man3p/strtoimax.3p create mode 100644 upstream/archlinux/man3p/strtok.3p create mode 100644 upstream/archlinux/man3p/strtol.3p create mode 100644 upstream/archlinux/man3p/strtold.3p create mode 100644 upstream/archlinux/man3p/strtoll.3p create mode 100644 upstream/archlinux/man3p/strtoul.3p create mode 100644 upstream/archlinux/man3p/strtoumax.3p create mode 100644 upstream/archlinux/man3p/strxfrm.3p create mode 100644 upstream/archlinux/man3p/swab.3p create mode 100644 upstream/archlinux/man3p/swprintf.3p create mode 100644 upstream/archlinux/man3p/swscanf.3p create mode 100644 upstream/archlinux/man3p/symlink.3p create mode 100644 upstream/archlinux/man3p/sync.3p create mode 100644 upstream/archlinux/man3p/sysconf.3p create mode 100644 upstream/archlinux/man3p/syslog.3p create mode 100644 upstream/archlinux/man3p/system.3p create mode 100644 upstream/archlinux/man3p/tan.3p create mode 100644 upstream/archlinux/man3p/tanh.3p create mode 100644 upstream/archlinux/man3p/tanl.3p create mode 100644 upstream/archlinux/man3p/tcdrain.3p create mode 100644 upstream/archlinux/man3p/tcflow.3p create mode 100644 upstream/archlinux/man3p/tcflush.3p create mode 100644 upstream/archlinux/man3p/tcgetattr.3p create mode 100644 upstream/archlinux/man3p/tcgetpgrp.3p create mode 100644 upstream/archlinux/man3p/tcgetsid.3p create mode 100644 upstream/archlinux/man3p/tcsendbreak.3p create mode 100644 upstream/archlinux/man3p/tcsetattr.3p create mode 100644 upstream/archlinux/man3p/tcsetpgrp.3p create mode 100644 upstream/archlinux/man3p/tdelete.3p create mode 100644 upstream/archlinux/man3p/telldir.3p create mode 100644 upstream/archlinux/man3p/tempnam.3p create mode 100644 upstream/archlinux/man3p/tfind.3p create mode 100644 upstream/archlinux/man3p/tgamma.3p create mode 100644 upstream/archlinux/man3p/time.3p create mode 100644 upstream/archlinux/man3p/timer_create.3p create mode 100644 upstream/archlinux/man3p/timer_delete.3p create mode 100644 upstream/archlinux/man3p/timer_getoverrun.3p create mode 100644 upstream/archlinux/man3p/times.3p create mode 100644 upstream/archlinux/man3p/timezone.3p create mode 100644 upstream/archlinux/man3p/tmpfile.3p create mode 100644 upstream/archlinux/man3p/tmpnam.3p create mode 100644 upstream/archlinux/man3p/toascii.3p create mode 100644 upstream/archlinux/man3p/tolower.3p create mode 100644 upstream/archlinux/man3p/toupper.3p create mode 100644 upstream/archlinux/man3p/towctrans.3p create mode 100644 upstream/archlinux/man3p/towlower.3p create mode 100644 upstream/archlinux/man3p/towupper.3p create mode 100644 upstream/archlinux/man3p/trunc.3p create mode 100644 upstream/archlinux/man3p/truncate.3p create mode 100644 upstream/archlinux/man3p/truncf.3p create mode 100644 upstream/archlinux/man3p/tsearch.3p create mode 100644 upstream/archlinux/man3p/ttyname.3p create mode 100644 upstream/archlinux/man3p/twalk.3p create mode 100644 upstream/archlinux/man3p/tzset.3p create mode 100644 upstream/archlinux/man3p/ulimit.3p create mode 100644 upstream/archlinux/man3p/umask.3p create mode 100644 upstream/archlinux/man3p/uname.3p create mode 100644 upstream/archlinux/man3p/ungetc.3p create mode 100644 upstream/archlinux/man3p/ungetwc.3p create mode 100644 upstream/archlinux/man3p/unlink.3p create mode 100644 upstream/archlinux/man3p/unlockpt.3p create mode 100644 upstream/archlinux/man3p/unsetenv.3p create mode 100644 upstream/archlinux/man3p/uselocale.3p create mode 100644 upstream/archlinux/man3p/utime.3p create mode 100644 upstream/archlinux/man3p/utimensat.3p create mode 100644 upstream/archlinux/man3p/va_arg.3p create mode 100644 upstream/archlinux/man3p/vfprintf.3p create mode 100644 upstream/archlinux/man3p/vfscanf.3p create mode 100644 upstream/archlinux/man3p/vfwprintf.3p create mode 100644 upstream/archlinux/man3p/vfwscanf.3p create mode 100644 upstream/archlinux/man3p/vprintf.3p create mode 100644 upstream/archlinux/man3p/vscanf.3p create mode 100644 upstream/archlinux/man3p/vsnprintf.3p create mode 100644 upstream/archlinux/man3p/vsscanf.3p create mode 100644 upstream/archlinux/man3p/vswprintf.3p create mode 100644 upstream/archlinux/man3p/vswscanf.3p create mode 100644 upstream/archlinux/man3p/vwprintf.3p create mode 100644 upstream/archlinux/man3p/vwscanf.3p create mode 100644 upstream/archlinux/man3p/wait.3p create mode 100644 upstream/archlinux/man3p/waitid.3p create mode 100644 upstream/archlinux/man3p/waitpid.3p create mode 100644 upstream/archlinux/man3p/wcpcpy.3p create mode 100644 upstream/archlinux/man3p/wcpncpy.3p create mode 100644 upstream/archlinux/man3p/wcrtomb.3p create mode 100644 upstream/archlinux/man3p/wcscasecmp.3p create mode 100644 upstream/archlinux/man3p/wcscat.3p create mode 100644 upstream/archlinux/man3p/wcschr.3p create mode 100644 upstream/archlinux/man3p/wcscmp.3p create mode 100644 upstream/archlinux/man3p/wcscoll.3p create mode 100644 upstream/archlinux/man3p/wcscpy.3p create mode 100644 upstream/archlinux/man3p/wcscspn.3p create mode 100644 upstream/archlinux/man3p/wcsdup.3p create mode 100644 upstream/archlinux/man3p/wcsftime.3p create mode 100644 upstream/archlinux/man3p/wcslen.3p create mode 100644 upstream/archlinux/man3p/wcsncasecmp.3p create mode 100644 upstream/archlinux/man3p/wcsncat.3p create mode 100644 upstream/archlinux/man3p/wcsncmp.3p create mode 100644 upstream/archlinux/man3p/wcsncpy.3p create mode 100644 upstream/archlinux/man3p/wcsnlen.3p create mode 100644 upstream/archlinux/man3p/wcsnrtombs.3p create mode 100644 upstream/archlinux/man3p/wcspbrk.3p create mode 100644 upstream/archlinux/man3p/wcsrchr.3p create mode 100644 upstream/archlinux/man3p/wcsrtombs.3p create mode 100644 upstream/archlinux/man3p/wcsspn.3p create mode 100644 upstream/archlinux/man3p/wcsstr.3p create mode 100644 upstream/archlinux/man3p/wcstod.3p create mode 100644 upstream/archlinux/man3p/wcstoimax.3p create mode 100644 upstream/archlinux/man3p/wcstok.3p create mode 100644 upstream/archlinux/man3p/wcstol.3p create mode 100644 upstream/archlinux/man3p/wcstold.3p create mode 100644 upstream/archlinux/man3p/wcstoll.3p create mode 100644 upstream/archlinux/man3p/wcstombs.3p create mode 100644 upstream/archlinux/man3p/wcstoul.3p create mode 100644 upstream/archlinux/man3p/wcstoumax.3p create mode 100644 upstream/archlinux/man3p/wcswidth.3p create mode 100644 upstream/archlinux/man3p/wcsxfrm.3p create mode 100644 upstream/archlinux/man3p/wctob.3p create mode 100644 upstream/archlinux/man3p/wctomb.3p create mode 100644 upstream/archlinux/man3p/wctrans.3p create mode 100644 upstream/archlinux/man3p/wctype.3p create mode 100644 upstream/archlinux/man3p/wcwidth.3p create mode 100644 upstream/archlinux/man3p/wmemchr.3p create mode 100644 upstream/archlinux/man3p/wmemcmp.3p create mode 100644 upstream/archlinux/man3p/wmemcpy.3p create mode 100644 upstream/archlinux/man3p/wmemmove.3p create mode 100644 upstream/archlinux/man3p/wmemset.3p create mode 100644 upstream/archlinux/man3p/wordexp.3p create mode 100644 upstream/archlinux/man3p/wprintf.3p create mode 100644 upstream/archlinux/man3p/write.3p create mode 100644 upstream/archlinux/man3p/writev.3p create mode 100644 upstream/archlinux/man3p/wscanf.3p create mode 100644 upstream/archlinux/man3p/y0.3p (limited to 'upstream/archlinux/man3p') diff --git a/upstream/archlinux/man3p/FD_CLR.3p b/upstream/archlinux/man3p/FD_CLR.3p new file mode 100644 index 00000000..52ca6ed1 --- /dev/null +++ b/upstream/archlinux/man3p/FD_CLR.3p @@ -0,0 +1,43 @@ +'\" et +.TH FD_CLR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +FD_CLR +\(em macros for synchronous I/O multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +void FD_CLR(int \fIfd\fP, fd_set *\fIfdset\fP); +int FD_ISSET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_SET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_ZERO(fd_set *\fIfdset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpselect\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/_Exit.3p b/upstream/archlinux/man3p/_Exit.3p new file mode 100644 index 00000000..10931b06 --- /dev/null +++ b/upstream/archlinux/man3p/_Exit.3p @@ -0,0 +1,461 @@ +'\" et +.TH _EXIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +_Exit, +_exit +\(em terminate a process +.SH SYNOPSIS +.LP +.nf +#include +.P +void _Exit(int \fIstatus\fP); +.P +#include +.P +void _exit(int \fIstatus\fP); +.fi +.SH DESCRIPTION +For +\fI_Exit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The value of +.IR status +may be 0, EXIT_SUCCESS, EXIT_FAILURE, +or any other value, though only the least significant 8 bits (that is, +.IR status +& 0377) shall be available from +\fIwait\fR() +and +\fIwaitpid\fR(); +the full value shall be available from +\fIwaitid\fR() +and in the +.BR siginfo_t +passed to a signal handler for SIGCHLD. +.P +The +\fI_Exit\fR() +and +\fI_exit\fR() +functions shall be functionally equivalent. +.P +The +\fI_Exit\fR() +and +\fI_exit\fR() +functions shall not call functions registered with +\fIatexit\fR() +nor any registered signal handlers. +Open streams shall not be flushed. +Whether open streams are closed (without flushing) is +implementation-defined. Finally, the calling process shall be +terminated with the consequences described below. +.SS "Consequences of Process Termination" +.P +Process termination caused by any reason shall have the following +consequences: +.TP 10 +.BR Note: +These consequences are all extensions to the ISO\ C standard and are not further +CX shaded. However, functionality relating to the XSI option is shaded. +.P +.IP " *" 4 +All of the file descriptors, directory streams, conversion descriptors, +and message catalog descriptors open in the calling process shall +be closed. +.IP " *" 4 +If the parent process of the calling process has set its SA_NOCLDWAIT +flag or has set the action for the SIGCHLD signal to SIG_IGN: +.RS 4 +.IP -- 4 +The process' status information (see +.IR "Section 2.13" ", " "Status Information"), +if any, shall be discarded. +.IP -- 4 +The lifetime of the calling process shall end immediately. If +SA_NOCLDWAIT is set, it is implementation-defined whether a SIGCHLD +signal is sent to the parent process. +.IP -- 4 +If a thread in the parent process of the calling process is blocked in +\fIwait\fR(), +\fIwaitpid\fR(), +or +\fIwaitid\fR(), +and the parent process has no remaining child processes in the +set of waited-for children, the +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +function shall fail and set +.IR errno +to +.BR [ECHILD] . +.P +Otherwise: +.IP -- 4 +Status information (see +.IR "Section 2.13" ", " "Status Information") +shall be generated. +.IP -- 4 +The calling process shall be transformed into a zombie process. Its +status information shall be made available to the parent process +until the process' lifetime ends. +.IP -- 4 +The process' lifetime shall end once its parent obtains the process' +status information via a currently-blocked or future call to +\fIwait\fR(), +\fIwaitid\fR() +(without WNOWAIT), or +\fIwaitpid\fR(). +.IP -- 4 +If one or more threads in the parent process of the calling process is +blocked in a call to +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +awaiting termination of the process, one (or, if any are calling +\fIwaitid\fR() +with WNOWAIT, possibly more) of these threads shall obtain the +process' status information as specified in +.IR "Section 2.13" ", " "Status Information" +and become unblocked. +.IP -- 4 +A SIGCHLD shall be sent to the parent process. +.RE +.IP " *" 4 +Termination of a process does not directly terminate its children. +The sending of a SIGHUP signal as described below indirectly +terminates children in some circumstances. +.IP " *" 4 +The parent process ID of all of the existing child processes and +zombie processes of the calling process shall be set to the process ID +of an implementation-defined system process. That is, these processes +shall be inherited by a special system process. +.IP " *" 4 +Each attached shared-memory segment is detached and the value of +.IR shm_nattch +(see +\fIshmget\fR()) +in the data structure associated with its shared memory ID +shall be decremented by 1. +.IP " *" 4 +For each semaphore for which the calling process has set a +.IR semadj +value (see +\fIsemop\fR()), +that value shall be added to the +.IR semval +of the specified semaphore. +.IP " *" 4 +If the process is a controlling process, the SIGHUP +signal shall be sent to each process in the foreground process group of +the controlling terminal belonging to the calling process. +.IP " *" 4 +If the process is a controlling process, the controlling terminal +associated with the session shall be disassociated from the session, +allowing it to be acquired by a new controlling process. +.IP " *" 4 +If the exit of the process causes a process group to become orphaned, +and if any member of the newly-orphaned process group is stopped, then +a SIGHUP signal followed by a SIGCONT signal shall be sent to each +process in the newly-orphaned process group. +.IP " *" 4 +All open named semaphores in the calling process shall be closed as +if by appropriate calls to +\fIsem_close\fR(). +.IP " *" 4 +Any memory locks established by the process via calls to +\fImlockall\fR() +or +\fImlock\fR() +shall be removed. If locked pages in the address space of the calling +process are also mapped into the address spaces of other processes and +are locked by those processes, the locks established by the other +processes shall be unaffected by the call by this process to +\fI_Exit\fR() +or +\fI_exit\fR(). +.IP " *" 4 +Memory mappings that were created in the process shall be unmapped +before the process is destroyed. +.IP " *" 4 +Any blocks of typed memory that were mapped in the calling process +shall be unmapped, as if +\fImunmap\fR() +was implicitly called to unmap them. +.IP " *" 4 +All open message queue descriptors in the calling process shall be +closed as if by appropriate calls to +\fImq_close\fR(). +.IP " *" 4 +Any outstanding cancelable asynchronous I/O operations may be +canceled. Those asynchronous I/O operations that are not canceled +shall complete as if the +\fI_Exit\fR() +or +\fI_exit\fR() +operation had not yet occurred, but any associated signal notifications +shall be suppressed. The +\fI_Exit\fR() +or +\fI_exit\fR() +operation may block awaiting such I/O completion. Whether any +I/O is canceled, and which I/O may be canceled upon +\fI_Exit\fR() +or +\fI_exit\fR(), +is implementation-defined. +.IP " *" 4 +Threads terminated by a call to +\fI_Exit\fR() +or +\fI_exit\fR() +shall not invoke their cancellation cleanup handlers or per-thread data +destructors. +.IP " *" 4 +If the calling process is a trace controller process, any trace streams +that were created by the calling process shall be shut down as +described by the +\fIposix_trace_shutdown\fR() +function, and mapping of trace event names to trace event type identifiers +of any process built for these trace streams may be deallocated. +.SH "RETURN VALUE" +These functions do not return. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Normally applications should use +\fIexit\fR() +rather than +\fI_Exit\fR() +or +\fI_exit\fR(). +.SH RATIONALE +.SS "Process Termination" +.P +Early proposals drew a distinction between normal and abnormal process +termination. Abnormal termination was caused only by certain signals +and resulted in implementation-defined ``actions'', as discussed below. +Subsequent proposals distinguished three types of termination: +\fInormal termination\fP (as in the current specification), \fIsimple +abnormal termination\fP, and \fIabnormal termination with actions\fP. +Again the distinction between the two types of abnormal termination was +that they were caused by different signals and that +implementation-defined actions would result in the latter case. Given +that these actions were completely implementation-defined, the early +proposals were only saying when the actions could occur and how their +occurrence could be detected, but not what they were. This was of +little or no use to conforming applications, and thus the distinction is +not made in this volume of POSIX.1\(hy2017. +.P +The implementation-defined actions usually include, in most +historical implementations, the creation of a file named +.BR core +in the current working directory of the process. This file contains an +image of the memory of the process, together with descriptive +information about the process, perhaps sufficient to reconstruct the +state of the process at the receipt of the signal. +.P +There is a potential security problem in creating a +.BR core +file if the process was set-user-ID +and the current user is not the owner of the program, if the process +was set-group-ID +and none of the user's groups match the group of the program, or if the +user does not have permission to write in the current directory. In +this situation, an implementation either should not create a +.BR core +file or should make it unreadable by the user. +.P +Despite the silence of this volume of POSIX.1\(hy2017 on this feature, applications are +advised not to create files named +.BR core +because of potential conflicts in many implementations. Some +implementations use a name other than +.BR core +for the file; for example, by appending the process ID to the filename. +.SS "Terminating a Process" +.P +It is important that the consequences of process termination as +described occur regardless of whether the process called +\fI_exit\fR() +(perhaps indirectly through +\fIexit\fR()) +or instead was terminated due to a signal or for some other reason. +Note that in the specific case of +\fIexit\fR() +this means that the +.IR status +argument to +\fIexit\fR() +is treated in the same way as the +.IR status +argument to +\fI_exit\fR(). +.P +A language other than C may have other termination primitives than the +C-language +\fIexit\fR() +function, and programs written in such a language should use its native +termination primitives, but those should have as part of their function +the behavior of +\fI_exit\fR() +as described. Implementations in languages other than C are outside +the scope of this version of this volume of POSIX.1\(hy2017, however. +.P +As required by the ISO\ C standard, using +.BR return +from +\fImain\fR() +has the same behavior (other than with respect to language scope +issues) as calling +\fIexit\fR() +with the returned value. Reaching the end of the +\fImain\fR() +function has the same behavior as calling +.IR exit (0). +.P +A value of zero (or EXIT_SUCCESS, which is required to be zero) +for the argument +.IR status +conventionally indicates successful termination. This corresponds to +the specification for +\fIexit\fR() +in the ISO\ C standard. The convention is followed by utilities such as +.IR make +and various shells, which interpret a zero status +from a child process as success. For this reason, applications should +not call \fIexit\fP(0) or \fI_exit\fP(0) when they terminate +unsuccessfully; for example, in signal-catching functions. +.P +Historically, the implementation-defined process that inherits +children whose parents have terminated without waiting on them is +called +.IR init +and has a process ID of 1. +.P +The sending of a SIGHUP +to the foreground process group when a controlling process terminates +corresponds to somewhat different historical implementations. In System +V, the kernel sends a +SIGHUP on termination of (essentially) a controlling process. In 4.2 BSD, +the kernel does not send SIGHUP in a case like this, but the termination +of a controlling process is usually noticed by a system daemon, which +arranges to send a SIGHUP to the foreground process group with the +\fIvhangup\fR() +function. However, in 4.2 BSD, due to the behavior of the shells that +support job control, +the controlling process is usually a shell with no other processes in +its process group. Thus, a change to make +\fI_exit\fR() +behave this way in such systems should not cause problems with existing +applications. +.P +The termination of a process may cause a process group to become +orphaned in either of two ways. +The connection of a process group to its parent(s) outside of the group +depends on both the parents and their children. Thus, a process group +may be orphaned by the termination of the last connecting parent +process outside of the group or by the termination of the last direct +descendant of the parent process(es). In either case, if the +termination of a process causes a process group to become orphaned, +processes within the group are disconnected from their job control +shell, which no longer has any information on the existence of the +process group. Stopped processes within the group would languish +forever. In order to avoid this problem, newly orphaned process groups +that contain stopped processes are sent a SIGHUP signal and a SIGCONT +signal to indicate that they have been disconnected from their +session. +The SIGHUP signal causes the process group members to terminate unless +they are catching or ignoring SIGHUP. Under most circumstances, all of +the members of the process group are stopped if any of them are +stopped. +.P +The action of sending a SIGHUP and a SIGCONT signal to members of a +newly orphaned process group is similar to the action of 4.2 BSD, which +sends SIGHUP and SIGCONT to each stopped child of an exiting process. +If such children exit in response to the SIGHUP, any additional +descendants receive similar treatment at that time. In this volume of POSIX.1\(hy2017, the +signals are sent to the entire process group at the same time. Also, +in this volume of POSIX.1\(hy2017, but not in 4.2 BSD, stopped processes may be orphaned, but +may be members of a process group that is not orphaned; therefore, the +action taken at +\fI_exit\fR() +must consider processes other than child processes. +.P +It is possible for a process group to be orphaned by a call to +\fIsetpgid\fR() +or +\fIsetsid\fR(), +as well as by process termination. This volume of POSIX.1\(hy2017 does not require sending +SIGHUP and SIGCONT in those cases, because, unlike process termination, +those cases are not caused accidentally by applications that are +unaware of job control. An implementation can choose to send SIGHUP +and SIGCONT in those cases as an extension; such an extension must be +documented as required in +.IR . +.P +The ISO/IEC\ 9899:\|1999 standard adds the +\fI_Exit\fR() +function that results in immediate program termination without +triggering signals or +\fIatexit\fR()-registered +functions. In POSIX.1\(hy2008, this is equivalent to the +\fI_exit\fR() +function. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatexit\fR\^(\|)", +.IR "\fIexit\fR\^(\|)", +.IR "\fImlock\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/_longjmp.3p b/upstream/archlinux/man3p/_longjmp.3p new file mode 100644 index 00000000..ee9e8048 --- /dev/null +++ b/upstream/archlinux/man3p/_longjmp.3p @@ -0,0 +1,132 @@ +'\" et +.TH _LONGJMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +_longjmp, +_setjmp +\(em non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +void _longjmp(jmp_buf \fIenv\fP, int \fIval\fP); +int _setjmp(jmp_buf \fIenv\fP); +.fi +.SH DESCRIPTION +The +\fI_longjmp\fR() +and +\fI_setjmp\fR() +functions shall be equivalent to +\fIlongjmp\fR() +and +\fIsetjmp\fR(), +respectively, with the additional restriction that +\fI_longjmp\fR() +and +\fI_setjmp\fR() +shall not manipulate the signal mask. +.P +If +\fI_longjmp\fR() +is called even though +.IR env +was never initialized by a call to +\fI_setjmp\fR(), +or when the last such call was in a function that has since returned, +the results are undefined. +.SH "RETURN VALUE" +Refer to +.IR "\fIlongjmp\fR\^(\|)" +and +.IR "\fIsetjmp\fR\^(\|)". +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If +\fI_longjmp\fR() +is executed and the environment in which +\fI_setjmp\fR() +was executed no longer exists, errors can occur. The conditions under +which the environment of the +\fI_setjmp\fR() +no longer exists include exiting the function that contains the +\fI_setjmp\fR() +call, and exiting an inner block with temporary storage. This +condition might not be detectable, in which case the +\fI_longjmp\fR() +occurs and, if the environment no longer exists, the contents of the +temporary storage of an inner block are unpredictable. This condition +might also cause unexpected process termination. If the function has +returned, the results are undefined. +.P +Passing +\fIlongjmp\fR() +a pointer to a buffer not created by +\fIsetjmp\fR(), +passing +\fI_longjmp\fR() +a pointer to a buffer not created by +\fI_setjmp\fR(), +passing +\fIsiglongjmp\fR() +a pointer to a buffer not created by +\fIsigsetjmp\fR(), +or passing any of these three functions a buffer that has been modified +by the user can cause all the problems listed above, and more. +.P +The +\fI_longjmp\fR() +and +\fI_setjmp\fR() +functions are included to support programs written to historical system +interfaces. New applications should use +\fIsiglongjmp\fR() +and +\fIsigsetjmp\fR() +respectively. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fI_longjmp\fR() +and +\fI_setjmp\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/_tolower.3p b/upstream/archlinux/man3p/_tolower.3p new file mode 100644 index 00000000..67f63892 --- /dev/null +++ b/upstream/archlinux/man3p/_tolower.3p @@ -0,0 +1,74 @@ +'\" et +.TH _TOLOWER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +_tolower +\(em transliterate uppercase characters to lowercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int _tolower(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fI_tolower\fR() +macro shall be equivalent to \fItolower\fP(\fIc\fP) except that the +application shall ensure that the argument +.IR c +is an uppercase letter. +.SH "RETURN VALUE" +Upon successful completion, +\fI_tolower\fR() +shall return the lowercase letter corresponding to the argument +passed. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fItolower\fR() +function instead of the obsolescent +\fI_tolower\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fI_tolower\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fItolower\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/_toupper.3p b/upstream/archlinux/man3p/_toupper.3p new file mode 100644 index 00000000..444796e5 --- /dev/null +++ b/upstream/archlinux/man3p/_toupper.3p @@ -0,0 +1,74 @@ +'\" et +.TH _TOUPPER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +_toupper +\(em transliterate lowercase characters to uppercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int _toupper(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fI_toupper\fR() +macro shall be equivalent to +\fItoupper\fR() +except that the application shall ensure that the argument +.IR c +is a lowercase letter. +.SH "RETURN VALUE" +Upon successful completion, +\fI_toupper\fR() +shall return the uppercase letter corresponding to the argument passed. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fItoupper\fR() +function instead of the obsolescent +\fI_toupper\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fI_toupper\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIislower\fR\^(\|)", +.IR "\fItoupper\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/a64l.3p b/upstream/archlinux/man3p/a64l.3p new file mode 100644 index 00000000..c260ac43 --- /dev/null +++ b/upstream/archlinux/man3p/a64l.3p @@ -0,0 +1,161 @@ +'\" et +.TH A64L "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +a64l, +l64a +\(em convert between a 32-bit integer and a radix-64 ASCII string +.SH SYNOPSIS +.LP +.nf +#include +.P +long a64l(const char *\fIs\fP); +char *l64a(long \fIvalue\fP); +.fi +.SH DESCRIPTION +These functions maintain numbers stored in radix-64 ASCII +characters. This is a notation by which 32-bit integers can be +represented by up to six characters; each character represents a digit +in radix-64 notation. If the type +.BR long +contains more than 32 bits, only the low-order 32 bits shall be used for +these operations. +.P +The characters used to represent digits are +.BR '.' +(dot) for 0, +.BR '/' +for 1, +.BR '0' +through +.BR '9' +for [2,11], +.BR 'A' +through +.BR 'Z' +for [12,37], and +.BR 'a' +through +.BR 'z' +for [38,63]. +.P +The +\fIa64l\fR() +function shall take a pointer to a radix-64 representation, in which +the first digit is the least significant, and return the corresponding +.BR long +value. If the string pointed to by +.IR s +contains more than six characters, +\fIa64l\fR() +shall use the first six. If the first six characters of the string +contain a null terminator, +\fIa64l\fR() +shall use only characters preceding the null terminator. The +\fIa64l\fR() +function shall scan the character string from left to right with the +least significant digit on the left, decoding each character as a 6-bit +radix-64 number. If the type +.BR long +contains more than 32 bits, the resulting value is sign-extended. The +behavior of +\fIa64l\fR() +is unspecified if +.IR s +is a null pointer or the string pointed to by +.IR s +was not generated by a previous call to +\fIl64a\fR(). +.P +The +\fIl64a\fR() +function shall take a +.BR long +argument and return a pointer to the corresponding radix-64 +representation. The behavior of +\fIl64a\fR() +is unspecified if +.IR value +is negative. +.P +The value returned by +\fIl64a\fR() +may be a pointer into a static buffer. Subsequent calls to +\fIl64a\fR() +may overwrite the buffer. +.P +The +\fIl64a\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIa64l\fR() +shall return the +.BR long +value resulting from conversion of the input string. If a string +pointed to by +.IR s +is an empty string, +\fIa64l\fR() +shall return 0L. +.P +The +\fIl64a\fR() +function shall return a pointer to the radix-64 representation. If +.IR value +is 0L, +\fIl64a\fR() +shall return a pointer to an empty string. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the type +.BR long +contains more than 32 bits, the result of +\fIa64l\fP(\fIl64a\fP(\fIx\fP)) is +.IR x +in the low-order 32 bits. +.SH RATIONALE +This is not the same encoding as used by either encoding variant +of the +.IR uuencode +utility. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtoul\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIuuencode\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/abort.3p b/upstream/archlinux/man3p/abort.3p new file mode 100644 index 00000000..26a87be2 --- /dev/null +++ b/upstream/archlinux/man3p/abort.3p @@ -0,0 +1,136 @@ +'\" et +.TH ABORT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +abort +\(em generate an abnormal process abort +.SH SYNOPSIS +.LP +.nf +#include +.P +void abort(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIabort\fR() +function shall cause abnormal process termination to occur, unless the +signal SIGABRT is being caught and the signal handler does not return. +.P +The abnormal termination processing shall include the default actions +defined for SIGABRT and may include an attempt to effect +\fIfclose\fR() +on all open streams. +.P +The SIGABRT signal shall be sent to the calling process as if by means +of +\fIraise\fR() +with the argument SIGABRT. +.P +The status made available to +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +by +\fIabort\fR() +shall be that of a process terminated by the SIGABRT signal. +The +\fIabort\fR() +function shall override blocking or ignoring the SIGABRT signal. +.SH "RETURN VALUE" +The +\fIabort\fR() +function shall not return. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Catching the signal is intended to provide the application developer with +a portable means to abort processing, free from possible interference +from any implementation-supplied functions. +.SH RATIONALE +The ISO/IEC\ 9899:\|1999 standard requires the +\fIabort\fR() +function to be async-signal-safe. Since POSIX.1\(hy2008 defers to the ISO\ C standard, +this required a change to the DESCRIPTION from ``shall include the +effect of +\fIfclose\fR()'' +to ``may include an attempt to effect +\fIfclose\fR().'' +.P +The revised wording permits some backwards-compatibility and avoids a +potential deadlock situation. +.P +The Open Group Base Resolution bwg2002\(hy003 is applied, removing the +following XSI shaded paragraph from the DESCRIPTION: +.P +``On XSI-conformant systems, in addition the abnormal termination +processing shall include the effect of +\fIfclose\fR() +on message catalog descriptors.'' +.P +There were several reasons to remove this paragraph: +.IP " *" 4 +No special processing of open message catalogs needs to be performed +prior to abnormal process termination. +.IP " *" 4 +The main reason to specifically mention that +\fIabort\fR() +includes the effect of +\fIfclose\fR() +on open streams is to flush output queued on the stream. Message +catalogs in this context are read-only and, therefore, do not need to +be flushed. +.IP " *" 4 +The effect of +\fIfclose\fR() +on a message catalog descriptor is unspecified. Message catalog +descriptors are allowed, but not required to be implemented using a +file descriptor, but there is no mention in POSIX.1\(hy2008 of a message catalog +descriptor using a standard I/O stream FILE object as would be expected +by +\fIfclose\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexit\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/abs.3p b/upstream/archlinux/man3p/abs.3p new file mode 100644 index 00000000..e358260d --- /dev/null +++ b/upstream/archlinux/man3p/abs.3p @@ -0,0 +1,72 @@ +'\" et +.TH ABS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +abs +\(em return an integer absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +int abs(int \fIi\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIabs\fR() +function shall compute the absolute value of its integer operand, +.IR i . +If the result cannot be represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIabs\fR() +function shall return the absolute value of its integer operand. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +In two's-complement representation, the absolute value of the negative +integer with largest magnitude +{INT_MIN} +might not be representable. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfabs\fR\^(\|)", +.IR "\fIlabs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/accept.3p b/upstream/archlinux/man3p/accept.3p new file mode 100644 index 00000000..34885b81 --- /dev/null +++ b/upstream/archlinux/man3p/accept.3p @@ -0,0 +1,197 @@ +'\" et +.TH ACCEPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +accept +\(em accept a new connection on a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int accept(int \fIsocket\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIaccept\fR() +function shall extract the first connection on the queue of pending +connections, create a new socket with the same socket type protocol +and address family as the specified socket, and allocate a new file +descriptor for that socket. The file descriptor shall be allocated +as described in +.IR "Section 2.14" ", " "File Descriptor Allocation". +.P +The +\fIaccept\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies a socket that was created with +\fIsocket\fR(), +has been bound to an address with +\fIbind\fR(), +and has issued a successful call to +\fIlisten\fR(). +.IP "\fIaddress\fR" 12 +Either a null pointer, or a pointer to a +.BR sockaddr +structure where the address of the connecting socket shall be returned. +.IP "\fIaddress_len\fR" 12 +Either a null pointer, if +.IR address +is a null pointer, or a pointer to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +.P +If +.IR address +is not a null pointer, the address of the peer for the accepted +connection shall be stored in the +.BR sockaddr +structure pointed to by +.IR address , +and the length of this address shall be stored in the object pointed to +by +.IR address_len . +.P +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the protocol permits connections by unbound clients, and the peer is +not bound, then the value stored in the object pointed to by +.IR address +is unspecified. +.P +If the listen queue is empty of connection requests and O_NONBLOCK is +not set on the file descriptor for the socket, +\fIaccept\fR() +shall block until a connection is present. If the +\fIlisten\fR() +queue is empty of connection requests and O_NONBLOCK is set on the file +descriptor for the socket, +\fIaccept\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.P +The accepted socket cannot itself accept more connections. The original +socket remains open and can accept more connections. +.SH "RETURN VALUE" +Upon successful completion, +\fIaccept\fR() +shall return the non-negative file descriptor of the accepted socket. +Otherwise, \-1 shall be returned, +.IR errno +shall be set to indicate the error, and any object pointed to by +.IR address_len +shall remain unchanged. +.SH ERRORS +The +\fIaccept\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +O_NONBLOCK is set for the socket file descriptor and no connections are +present to be accepted. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNABORTED +.br +A connection has been aborted. +.TP +.BR EINTR +The +\fIaccept\fR() +function was interrupted by a signal that was caught before a valid +connection arrived. +.TP +.BR EINVAL +The +.IR socket +is not accepting connections. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum number of file descriptors in the system are already open. +.TP +.BR ENOBUFS +No buffer space is available. +.TP +.BR ENOMEM +There was insufficient memory available to complete the operation. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The socket type of the specified socket does not support accepting +connections. +.P +The +\fIaccept\fR() +function may fail if: +.TP +.BR EPROTO +A protocol error has occurred; +for example, the STREAMS protocol stack has not been initialized. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +When a connection is available, +\fIselect\fR() +indicates that the file descriptor for the socket is ready for reading. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "File Descriptor Allocation", +.IR "\fIbind\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/access.3p b/upstream/archlinux/man3p/access.3p new file mode 100644 index 00000000..edbff485 --- /dev/null +++ b/upstream/archlinux/man3p/access.3p @@ -0,0 +1,369 @@ +'\" et +.TH ACCESS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +access, faccessat +\(em determine accessibility of a file +descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int access(const char *\fIpath\fP, int \fIamode\fP); +.P +#include +.P +int faccessat(int \fIfd\fP, const char *\fIpath\fP, int \fIamode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIaccess\fR() +function shall check the file named by the pathname pointed to by the +.IR path +argument for accessibility according to the bit pattern contained in +.IR amode . +The checks for accessibility (including directory permissions +checked during pathname resolution) shall be performed using the +real user ID in place of the effective user ID and the real group +ID in place of the effective group ID. +.P +The value of +.IR amode +is either the bitwise-inclusive OR of the access permissions to be +checked (R_OK, W_OK, X_OK) or the existence test (F_OK). +.P +If any access permissions are checked, each shall be checked +individually, as described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.5" ", " "File Access Permissions", +except that where that description refers to execute permission for +a process with appropriate privileges, an implementation may indicate +success for X_OK even if execute permission is not granted to any user. +.P +The +\fIfaccessat\fR() +function, when called with a +.IR flag +value of zero, shall be equivalent to the +\fIaccess\fR() +function, except in the case where +.IR path +specifies a relative path. In this case the file whose accessibility is +to be determined shall be located relative to the directory associated +with the file descriptor +.IR fd +instead of the current working directory. +If the access mode of the open file description associated with +the file descriptor is not O_SEARCH, the function shall check +whether directory searches are permitted using the current +permissions of the directory underlying the file descriptor. +If the access mode is O_SEARCH, the function shall not perform the check. +.P +If +\fIfaccessat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and, if flag is +zero, the behavior shall be identical to a call to +\fIaccess\fR(). +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_EACCESS 12 +The checks for accessibility (including directory permissions +checked during pathname resolution) shall be performed using the +effective user ID and group ID instead of the real user ID and group ID +as required in a call to +\fIaccess\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. Otherwise, +these functions shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR 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. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EROFS +Write access is requested for a file on a read-only file system. +.P +The +\fIfaccessat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EINVAL +The value of the \fIamode\fP argument is invalid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +Write access is requested for a pure procedure (shared text) file that +is being executed. +.P +The +\fIfaccessat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Testing for the Existence of a File" +.P +The following example tests whether a file named +.BR myfile +exists in the +.BR /tmp +directory. +.sp +.RS 4 +.nf + +#include +\&... +int result; +const char *pathname = "/tmp/myfile"; +.P +result = access (pathname, F_OK); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Use of these functions is discouraged since by the time the +returned information is acted upon, it is out-of-date. (That is, +acting upon the information always leads to a time-of-check-to-time-of-use +race condition.) An application should instead attempt the action +itself and handle the +.BR [EACCES] +error that occurs if the file is not accessible (with a change of +effective user and group IDs beforehand, and perhaps a change back +afterwards, in the case where +\fIaccess\fR() +or +\fIfaccessat\fR() +without AT_EACCES would have been used.) +.P +Historically, one of the uses of +\fIaccess\fR() +was in set-user-ID root programs to check whether the user running +the program had access to a file. This relied on ``super-user'' +privileges which were granted based on the effective user ID being +zero, so that when +\fIaccess\fR() +used the real user ID to check accessibility those privileges +were not taken into account. On newer systems where privileges +can be assigned which have no association with user or group IDs, +if a program with such privileges calls +\fIaccess\fR(), +the change of IDs has no effect on the privileges and therefore +they are taken into account in the accessibility checks. Thus, +\fIaccess\fR() +(and +\fIfaccessat\fR() +with flag zero) cannot be used for this historical purpose in +such programs. Likewise, if a system provides any additional or +alternate file access control mechanisms that are not user ID-based, +they will still be taken into account. +.P +If a relative pathname is used, no account is taken of whether +the current directory (or the directory associated with the +file descriptor +.IR fd ) +is accessible via any absolute pathname. Applications using +\fIaccess\fR(), +or +\fIfaccessat\fR() +without AT_EACCES, may consequently act as if the file would be +accessible to a user with the real user ID and group ID of the +process when such a user would not in practice be able to access the file +because access would be denied at some point above the current directory +(or the directory associated with the file descriptor +.IR fd ) +in the file hierarchy. +.P +If +\fIaccess\fR() +or +\fIfaccessat\fR() +is used with W_OK to check for write access to a directory which has +the S_ISVTX bit set, a return value indicating the directory is +writable can be misleading since some operations on files in the +directory would not be permitted based on the ownership of those files +(see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection"). +.P +Additional values of +.IR amode +other than the set defined in the description may be valid; for +example, if a system has extended access controls. +.P +The use of the AT_EACCESS value for +.IR flag +enables functionality not available in +\fIaccess\fR(). +.SH RATIONALE +In early proposals, some inadequacies in the +\fIaccess\fR() +function led to the creation of an +\fIeaccess\fR() +function because: +.IP " 1." 4 +Historical implementations of +\fIaccess\fR() +do not test file access correctly when the process' +real user ID is +superuser. In particular, they always return zero when testing execute +permissions without regard to whether the file is executable. +.IP " 2." 4 +The superuser has complete access to all files on a system. As a +consequence, programs started by the superuser and switched to the +effective user ID +with lesser privileges cannot use +\fIaccess\fR() +to test their file access permissions. +.P +However, the historical model of +\fIeaccess\fR() +does not resolve problem (1), so this volume of POSIX.1\(hy2017 now allows +\fIaccess\fR() +to behave in the desired way because several implementations have +corrected the problem. It was also argued that problem (2) is more +easily solved by using +\fIopen\fR(), +\fIchdir\fR(), +or one of the +.IR exec +functions as appropriate and responding to the error, rather than +creating a new function that would not be as reliable. Therefore, +\fIeaccess\fR() +is not included in this volume of POSIX.1\(hy2017. +.P +The sentence concerning appropriate privileges and execute permission +bits +reflects the two possibilities implemented by historical +implementations when checking superuser access for X_OK. +.P +New implementations are discouraged from returning X_OK unless at least +one execution permission bit is set. +.P +The purpose of the +\fIfaccessat\fR() +function is to enable the checking of the accessibility of files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fIaccess\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfaccessat\fR() +function it can be guaranteed that the file tested for accessibility is +located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +These functions may be formally deprecated (for example, by shading +them OB) in a future version of this standard. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.5" ", " "File Access Permissions", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/acos.3p b/upstream/archlinux/man3p/acos.3p new file mode 100644 index 00000000..111b2eb4 --- /dev/null +++ b/upstream/archlinux/man3p/acos.3p @@ -0,0 +1,122 @@ +'\" et +.TH ACOS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +acos, +acosf, +acosl +\(em arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double acos(double \fIx\fP); +float acosf(float \fIx\fP); +long double acosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc cosine of +their argument +.IR x . +The value of +.IR x +should be in the range [\-1,1]. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc +cosine of +.IR x , +in the range [0,\(*p] radians. +.P +For finite values of +.IR x +not in the range [\-1,1], a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is +1, +0 shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and is not in the range [\-1,1], +or is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcos\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/acosh.3p b/upstream/archlinux/man3p/acosh.3p new file mode 100644 index 00000000..2eb98142 --- /dev/null +++ b/upstream/archlinux/man3p/acosh.3p @@ -0,0 +1,120 @@ +'\" et +.TH ACOSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +acosh, +acoshf, +acoshl +\(em inverse hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double acosh(double \fIx\fP); +float acoshf(float \fIx\fP); +long double acoshl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the inverse hyperbolic cosine of their +argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the inverse +hyperbolic cosine of their argument. +.P +For finite values of +.IR x +< 1, a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is +1, +0 shall be returned. +.P +If +.IR x +is +Inf, +Inf shall be returned. +.P +If +.IR x +is \-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and less than +1.0, +or is \-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcosh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/acosl.3p b/upstream/archlinux/man3p/acosl.3p new file mode 100644 index 00000000..ae75647a --- /dev/null +++ b/upstream/archlinux/man3p/acosl.3p @@ -0,0 +1,40 @@ +'\" et +.TH ACOSL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +acosl +\(em arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double acosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIacos\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/aio_cancel.3p b/upstream/archlinux/man3p/aio_cancel.3p new file mode 100644 index 00000000..e356840c --- /dev/null +++ b/upstream/archlinux/man3p/aio_cancel.3p @@ -0,0 +1,120 @@ +'\" et +.TH AIO_CANCEL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +aio_cancel +\(em cancel an asynchronous I/O request +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_cancel(int \fIfildes\fP, struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_cancel\fR() +function shall attempt to cancel one or more asynchronous I/O requests +currently outstanding against file descriptor +.IR fildes . +The +.IR aiocbp +argument points to the asynchronous I/O control block for a particular +request to be canceled. If +.IR aiocbp +is NULL, then all outstanding cancelable asynchronous I/O requests +against +.IR fildes +shall be canceled. +.P +Normal asynchronous notification shall occur for asynchronous I/O +operations that are successfully canceled. If there are requests that +cannot be canceled, then the normal asynchronous completion process +shall take place for those requests when they are completed. +.P +For requested operations that are successfully canceled, the associated +error status shall be set to +.BR [ECANCELED] +and the return status shall be \-1. For requested operations that are +not successfully canceled, the +.IR aiocbp +shall not be modified by +\fIaio_cancel\fR(). +.P +If +.IR aiocbp +is not NULL, then if +.IR fildes +does not have the same value as the file descriptor with which the +asynchronous operation was initiated, unspecified results occur. +.P +Which operations are cancelable is implementation-defined. +.SH "RETURN VALUE" +The +\fIaio_cancel\fR() +function shall return the value AIO_CANCELED +if the requested operation(s) were canceled. +The value AIO_NOTCANCELED +shall be returned if at least one of the requested operation(s) cannot +be canceled because it is in progress. In this case, the state of the +other operations, if any, referenced in the call to +\fIaio_cancel\fR() +is not indicated by the return value of +\fIaio_cancel\fR(). +The application may determine the state of affairs for these operations +by using +\fIaio_error\fR(). +The value AIO_ALLDONE +is returned if all of the operations have already completed. +Otherwise, the function shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_cancel\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/aio_error.3p b/upstream/archlinux/man3p/aio_error.3p new file mode 100644 index 00000000..2520beb3 --- /dev/null +++ b/upstream/archlinux/man3p/aio_error.3p @@ -0,0 +1,119 @@ +'\" et +.TH AIO_ERROR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +aio_error +\(em retrieve errors status for an asynchronous I/O operation +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_error(const struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_error\fR() +function shall return the error status associated with the +.BR aiocb +structure referenced by the +.IR aiocbp +argument. The error status for an asynchronous I/O operation is the +.IR errno +value that would be set by the corresponding +\fIread\fR(), +\fIwrite\fR(), +\fIfdatasync\fR(), +or +\fIfsync\fR() +operation. If the operation has not yet completed, then the error +status shall be equal to +.BR [EINPROGRESS] . +.P +If the +.BR aiocb +structure pointed to by +.IR aiocbp +is not associated with an operation that has been scheduled, the +results are undefined. +.SH "RETURN VALUE" +If the asynchronous I/O operation has completed successfully, then 0 +shall be returned. If the asynchronous operation has completed +unsuccessfully, then the error status, as described for +\fIread\fR(), +\fIwrite\fR(), +\fIfdatasync\fR(), +and +\fIfsync\fR(), +shall be returned. If the asynchronous I/O operation has not yet +completed, then +.BR [EINPROGRESS] +shall be returned. +.P +If the +\fIaio_error\fR() +function fails, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_error\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR aiocbp +argument does not refer to an asynchronous operation whose return +status has not yet been retrieved. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/aio_fsync.3p b/upstream/archlinux/man3p/aio_fsync.3p new file mode 100644 index 00000000..6590e08d --- /dev/null +++ b/upstream/archlinux/man3p/aio_fsync.3p @@ -0,0 +1,201 @@ +'\" et +.TH AIO_FSYNC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +aio_fsync +\(em asynchronous file synchronization +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_fsync(int \fIop\fP, struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_fsync\fR() +function shall asynchronously perform a file synchronization operation, +as specified by the +.IR op +argument, for I/O operations associated with the file indicated by the +file descriptor +.IR aio_fildes +member of the +.BR aiocb +structure referenced by the +.IR aiocbp +argument and queued at the time of the call to +\fIaio_fsync\fR(). +The function call shall return when the synchronization request has been +initiated or queued to the file or device (even when the data cannot be +synchronized immediately). +.P +If +.IR op +is O_DSYNC, +all currently queued I/O operations shall be completed as if by a call to +\fIfdatasync\fR(); +that is, as defined for synchronized I/O data integrity completion. +.P +If +.IR op +is O_SYNC, +all currently queued I/O operations shall be completed as if by a call to +\fIfsync\fR(); +that is, as defined for synchronized I/O file integrity completion. +If the +\fIaio_fsync\fR() +function fails, or if the operation queued by +\fIaio_fsync\fR() +fails, then outstanding I/O operations are not guaranteed to have been +completed. +.P +If +\fIaio_fsync\fR() +succeeds, then it is only the I/O that was queued at the time of the +call to +\fIaio_fsync\fR() +that is guaranteed to be forced to the relevant completion state. The +completion of subsequent I/O on the file descriptor is not guaranteed +to be completed in a synchronized fashion. +.P +The +.IR aiocbp +argument refers to an asynchronous I/O control block. The +.IR aiocbp +value may be used as an argument to +\fIaio_error\fR() +and +\fIaio_return\fR() +in order to determine the error status and return status, respectively, +of the asynchronous operation while it is proceeding. When the request +is queued, the error status for the operation is +.BR [EINPROGRESS] . +When all data has been successfully transferred, the error status shall +be reset to reflect the success or failure of the operation. If the +operation does not complete successfully, the error status for the +operation shall be set to indicate the error. The +.IR aio_sigevent +member determines the asynchronous notification to occur as specified +in +.IR "Section 2.4.1" ", " "Signal Generation and Delivery" +when all operations have achieved synchronized I/O completion. All +other members of the structure referenced by +.IR aiocbp +are ignored. If the control block referenced by +.IR aiocbp +becomes an illegal address prior to asynchronous I/O completion, then +the behavior is undefined. +.P +If the +\fIaio_fsync\fR() +function fails or +.IR aiocbp +indicates an error condition, data is not guaranteed to have been +successfully transferred. +.SH "RETURN VALUE" +The +\fIaio_fsync\fR() +function shall return the value 0 if the I/O operation is successfully +queued; otherwise, the function shall return the value \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_fsync\fR() +function shall fail if: +.TP +.BR EAGAIN +The requested asynchronous operation was not queued due to +temporary resource limitations. +.TP +.BR EBADF +The +.IR aio_fildes +member of the +.BR aiocb +structure referenced by the +.IR aiocbp +argument is not a valid file descriptor. +.TP +.BR EINVAL +This implementation does not support synchronized I/O for this file. +.TP +.BR EINVAL +The +.IR aio_fildes +member of the +.BR aiocb +structure refers to a file on which an +\fIfsync\fR() +operation is not possible. +.TP +.BR EINVAL +A value of +.IR op +other than O_DSYNC or O_SYNC was specified, or O_DSYNC was specified and +the implementation does not provide runtime support for the Synchronized +Input and Output option, or O_SYNC was specified and the implementation +does not provide runtime support for the File Synchronization option. +.P +In the event that any of the queued I/O operations fail, +\fIaio_fsync\fR() +shall return the error condition defined for +\fIread\fR() +and +\fIwrite\fR(). +The error is returned in the error status for the asynchronous operation, +which can be retrieved using +\fIaio_error\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Note that even if the file descriptor is not open for writing, if +there are any pending write requests on the underlying file, then +that I/O will be completed prior to the return of a call to +\fIaio_error\fR() +or +\fIaio_return\fR() +indicating that the operation has completed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfdatasync\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/aio_read.3p b/upstream/archlinux/man3p/aio_read.3p new file mode 100644 index 00000000..37b034b7 --- /dev/null +++ b/upstream/archlinux/man3p/aio_read.3p @@ -0,0 +1,210 @@ +'\" et +.TH AIO_READ "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +aio_read +\(em asynchronous read from a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_read(struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_read\fR() +function shall read \fIaiocbp\fP\->\fIaio_nbytes\fR from the file +associated with \fIaiocbp\fP\->\fIaio_fildes\fR into the buffer pointed +to by \fIaiocbp\fP\->\fIaio_buf\fR. The function call shall return when +the read request has been initiated or queued to the file or device +(even when the data cannot be delivered immediately). +.P +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to a base scheduling +priority minus \fIaiocbp\fP\->\fIaio_reqprio\fR. If Thread Execution +Scheduling is not supported, then the base scheduling priority is that +of the calling process; +.br +otherwise, the base scheduling priority is that of the calling thread. +.P +The +.IR aiocbp +value may be used as an argument to +\fIaio_error\fR() +and +\fIaio_return\fR() +in order to determine the error status and return status, respectively, +of the asynchronous operation while it is proceeding. If an error +condition is encountered during queuing, the function call shall return +without having initiated or queued the request. The requested +operation takes place at the absolute position in the file as given by +.IR aio_offset , +as if +\fIlseek\fR() +were called immediately prior to the operation with an +.IR offset +equal to +.IR aio_offset +and a +.IR whence +equal to SEEK_SET. +After a successful call to enqueue an asynchronous I/O operation, the +value of the file offset for the file is unspecified. +.P +The +.IR aio_sigevent +member specifies the notification which occurs when the request is +completed. +.P +The \fIaiocbp\fP\->\fIaio_lio_opcode\fR field shall be ignored by +\fIaio_read\fR(). +.P +The +.IR aiocbp +argument points to an +.BR aiocb +structure. If the buffer pointed to by \fIaiocbp\fP\->\fIaio_buf\fR or +the control block pointed to by +.IR aiocbp +becomes an illegal address prior to asynchronous I/O completion, then +the behavior is undefined. +.P +Simultaneous asynchronous operations using the same +.IR aiocbp +produce undefined results. +.P +If synchronized I/O is enabled on the file associated with +\fIaiocbp\fP\->\fIaio_fildes\fR, the behavior of this function shall +be according to the definitions of synchronized I/O data integrity +completion and synchronized I/O file integrity completion. +.P +For any system action that changes the process memory space while an +asynchronous I/O is outstanding to the address range being changed, the +result of that action is undefined. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP\->\fIaio_fildes\fR. +.SH "RETURN VALUE" +The +\fIaio_read\fR() +function shall return the value zero if the I/O operation is +successfully queued; otherwise, the function shall return the value +\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_read\fR() +function shall fail if: +.TP +.BR EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.P +Each of the following conditions may be detected synchronously at the +time of the call to +\fIaio_read\fR(), +or asynchronously. If any of the conditions below are detected +synchronously, the +\fIaio_read\fR() +function shall return \-1 and set +.IR errno +to the corresponding value. If any of the conditions below are +detected asynchronously, the return status of the asynchronous +operation is set to \-1, and the error status of the asynchronous +operation is set to the corresponding value. +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fP argument is not a valid file +descriptor open for reading. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid, +.br +\fIaiocbp\fP\->\fIaio_reqprio\fR is not a valid value, +or \fIaiocbp\fP\->\fIaio_nbytes\fR is an invalid value. +.P +In the case that the +\fIaio_read\fR() +successfully queues the I/O operation but the operation is subsequently +canceled or encounters an error, the return status of the asynchronous +operation is one of the values normally returned by the +\fIread\fR() +function call. In addition, the error status of the asynchronous +operation is set to one of the error statuses normally set by the +\fIread\fR() +function call, or one of the following values: +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file +descriptor open for reading. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid. +.P +The following condition may be detected synchronously or asynchronously: +.TP +.BR EOVERFLOW +The file is a regular file, \fIaiobcp\fP\->\fIaio_nbytes\fR is greater +than 0, and the starting offset in \fIaiobcp\fP\->\fIaio_offset\fR is +before the end-of-file and is at or beyond the offset maximum in the +open file description associated with \fIaiocbp\fP\->\fIaio_fildes\fR. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/aio_return.3p b/upstream/archlinux/man3p/aio_return.3p new file mode 100644 index 00000000..7f5e009f --- /dev/null +++ b/upstream/archlinux/man3p/aio_return.3p @@ -0,0 +1,122 @@ +'\" et +.TH AIO_RETURN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +aio_return +\(em retrieve return status of an asynchronous I/O operation +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t aio_return(struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_return\fR() +function shall return the return status associated with the +.BR aiocb +structure referenced by the +.IR aiocbp +argument. The return status for an asynchronous I/O operation is the +value that would be returned by the corresponding +\fIread\fR(), +\fIwrite\fR(), +or +\fIfsync\fR() +function call. If the error status for the operation is equal to +.BR [EINPROGRESS] , +then the return status for the operation is undefined. The +\fIaio_return\fR() +function may be called exactly once to retrieve the return status of a +given asynchronous operation; thereafter, if the same +.BR aiocb +structure is used in a call to +\fIaio_return\fR() +or +\fIaio_error\fR(), +an error may be returned. When the +.BR aiocb +structure referred to by +.IR aiocbp +is used to submit another asynchronous operation, then +\fIaio_return\fR() +may be successfully used to retrieve the return status of that +operation. +.SH "RETURN VALUE" +If the asynchronous I/O operation has completed, then the return +status, as described for +\fIread\fR(), +\fIwrite\fR(), +and +\fIfsync\fR(), +shall be returned. If the asynchronous I/O operation has not yet +completed, the results of +\fIaio_return\fR() +are undefined. +.P +If the +\fIaio_return\fR() +function fails, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_return\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR aiocbp +argument does not refer to an asynchronous operation whose return +status has not yet been retrieved. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/aio_suspend.3p b/upstream/archlinux/man3p/aio_suspend.3p new file mode 100644 index 00000000..60e26b75 --- /dev/null +++ b/upstream/archlinux/man3p/aio_suspend.3p @@ -0,0 +1,134 @@ +'\" et +.TH AIO_SUSPEND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +aio_suspend +\(em wait for an asynchronous I/O request +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_suspend(const struct aiocb *const \fIlist\fP[], int \fInent\fP, + const struct timespec *\fItimeout\fP); +.fi +.SH DESCRIPTION +The +\fIaio_suspend\fR() +function shall suspend the calling thread until at least one of the +asynchronous I/O operations referenced by the +.IR list +argument has completed, until a signal interrupts the function, or, if +.IR timeout +is not NULL, until the time interval specified by +.IR timeout +has passed. If any of the +.BR aiocb +structures in the list correspond to completed asynchronous I/O +operations (that is, the error status for the operation is not equal to +.BR [EINPROGRESS] ) +at the time of the call, the function shall return without suspending +the calling thread. The +.IR list +argument is an array of pointers to asynchronous I/O control blocks. +The +.IR nent +argument indicates the number of elements in the array. Each +.BR aiocb +structure pointed to has been used in initiating an asynchronous +I/O request via +\fIaio_read\fR(), +\fIaio_write\fR(), +or +\fIlio_listio\fR(). +This array may contain null pointers, which are ignored. If this array +contains pointers that refer to +.BR aiocb +structures that have not been used in submitting asynchronous I/O, the +effect is undefined. +.P +If the time interval indicated in the +.BR timespec +structure pointed to by +.IR timeout +passes before any of the I/O operations referenced by +.IR list +are completed, then +\fIaio_suspend\fR() +shall return with an error. +If the Monotonic Clock option is supported, the clock that shall be +used to measure this time interval shall be the CLOCK_MONOTONIC clock. +.SH "RETURN VALUE" +If the +\fIaio_suspend\fR() +function returns after one or more asynchronous I/O operations have +completed, the function shall return zero. Otherwise, the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.P +The application may determine which asynchronous I/O completed by +scanning the associated error and return status using +\fIaio_error\fR() +and +\fIaio_return\fR(), +respectively. +.SH ERRORS +The +\fIaio_suspend\fR() +function shall fail if: +.TP +.BR EAGAIN +No asynchronous I/O indicated in the list referenced by +.IR list +completed in the time interval indicated by +.IR timeout . +.TP +.BR EINTR +A signal interrupted the +\fIaio_suspend\fR() +function. Note that, since each asynchronous I/O operation may +possibly provoke a signal when it completes, this error return may be +caused by the completion of one (or more) of the very I/O operations +being awaited. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/aio_write.3p b/upstream/archlinux/man3p/aio_write.3p new file mode 100644 index 00000000..4b9ae1f8 --- /dev/null +++ b/upstream/archlinux/man3p/aio_write.3p @@ -0,0 +1,220 @@ +'\" et +.TH AIO_WRITE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +aio_write +\(em asynchronous write to a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int aio_write(struct aiocb *\fIaiocbp\fP); +.fi +.SH DESCRIPTION +The +\fIaio_write\fR() +function shall write \fIaiocbp\fP\->\fIaio_nbytes\fR to the file +associated with \fIaiocbp\fP\->\fIaio_fildes\fR from the buffer pointed +to by \fIaiocbp\fP\->\fIaio_buf\fR. The function shall return when +the write request has been initiated or, at a minimum, queued to the +file or device. +.P +If prioritized I/O is supported for this file, then the asynchronous +operation shall be submitted at a priority equal to a base scheduling +priority minus \fIaiocbp\fP\->\fIaio_reqprio\fR. If Thread Execution +Scheduling is not supported, then the base scheduling priority is that +of the calling process; +.br +otherwise, the base scheduling priority is that of the calling thread. +.P +The +.IR aiocbp +argument may be used as an argument to +\fIaio_error\fR() +and +\fIaio_return\fR() +in order to determine the error status and return status, respectively, +of the asynchronous operation while it is proceeding. +.P +The +.IR aiocbp +argument points to an +.BR aiocb +structure. If the buffer pointed to by \fIaiocbp\fP\->\fIaio_buf\fR or +the control block pointed to by +.IR aiocbp +becomes an illegal address prior to asynchronous I/O completion, then +the behavior is undefined. +.P +If O_APPEND is not set for the file descriptor +.IR aio_fildes , +then the requested operation shall take place at the absolute +position in the file as given by +.IR aio_offset , +as if +\fIlseek\fR() +were called immediately prior to the operation with an +.IR offset +equal to +.IR aio_offset +and a +.IR whence +equal to SEEK_SET. +If O_APPEND is set for the file descriptor, or if +.IR aio_fildes +is associated with a device that is incapable of seeking, write operations +append to the file in the same order as the calls were made, except +under circumstances described in +.IR "Section 2.8.2" ", " "Asynchronous I/O". +After a successful call to enqueue an asynchronous I/O operation, the +value of the file offset for the file is unspecified. +.P +The +.IR aio_sigevent +member specifies the notification which occurs when the request is +completed. +.P +The \fIaiocbp\fP\->\fIaio_lio_opcode\fR field shall be ignored by +\fIaio_write\fR(). +.P +Simultaneous asynchronous operations using the same +.IR aiocbp +produce undefined results. +.P +If synchronized I/O is enabled on the file associated with +\fIaiocbp\fP\->\fIaio_fildes\fR, the behavior of this function shall +be according to the definitions of synchronized I/O data integrity +completion, and synchronized I/O file integrity completion. +.P +For any system action that changes the process memory space while an +asynchronous I/O is outstanding to the address range being changed, the +result of that action is undefined. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fP\->\fIaio_fildes\fR. +.SH "RETURN VALUE" +The +\fIaio_write\fR() +function shall return the value zero if the I/O operation is +successfully queued; otherwise, the function shall return the value +\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIaio_write\fR() +function shall fail if: +.TP +.BR EAGAIN +The requested asynchronous I/O operation was not queued due to system +resource limitations. +.P +Each of the following conditions may be detected synchronously at the +time of the call to +\fIaio_write\fR(), +or asynchronously. If any of the conditions below are detected +synchronously, the +\fIaio_write\fR() +function shall return \-1 and set +.IR errno +to the corresponding value. If any of the conditions below are detected +asynchronously, the return status of the asynchronous operation shall +be set to \-1, and the error status of the asynchronous operation +is set to the corresponding value. +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file +descriptor open for writing. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid, +.br +\fIaiocbp\fP\->\fIaio_reqprio\fR is not a valid value, +or \fIaiocbp\fP\->\fIaio_nbytes\fR is an invalid value. +.P +In the case that the +\fIaio_write\fR() +successfully queues the I/O operation, the return status of the +asynchronous operation shall be one of the values normally returned +by the +\fIwrite\fR() +function call. If the operation is successfully queued but is +subsequently canceled or encounters an error, the error status for the +asynchronous operation contains one of the values normally set by the +\fIwrite\fR() +function call, or one of the following: +.TP +.BR EBADF +The \fIaiocbp\fP\->\fIaio_fildes\fR argument is not a valid file +descriptor open for writing. +.TP +.BR EINVAL +The file offset value implied by \fIaiocbp\fP\->\fIaio_offset\fR would +be invalid. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.P +The following condition may be detected synchronously or asynchronously: +.TP +.BR EFBIG +The file is a regular file, \fIaiobcp\fP\->\fIaio_nbytes\fR is greater +than 0, and the starting offset in \fIaiobcp\fP\->\fIaio_offset\fR is +at or beyond the offset maximum in the open file description associated +with \fIaiocbp\fP\->\fIaio_fildes\fR. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.8.2" ", " "Asynchronous I/O", +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlio_listio\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/alarm.3p b/upstream/archlinux/man3p/alarm.3p new file mode 100644 index 00000000..99fb0ab3 --- /dev/null +++ b/upstream/archlinux/man3p/alarm.3p @@ -0,0 +1,165 @@ +'\" et +.TH ALARM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +alarm +\(em schedule an alarm signal +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned alarm(unsigned \fIseconds\fP); +.fi +.SH DESCRIPTION +The +\fIalarm\fR() +function shall cause the system to generate a SIGALRM signal for the +process after the number of realtime seconds specified by +.IR seconds +have elapsed. Processor scheduling delays may prevent the process from +handling the signal as soon as it is generated. +.P +If +.IR seconds +is 0, a pending alarm request, if any, is canceled. +.P +Alarm requests are not stacked; only one SIGALRM generation can be +scheduled in this manner. If the SIGALRM signal has not yet been +generated, the call shall result in rescheduling the time at which the +SIGALRM signal is generated. +.P +Interactions between +\fIalarm\fR() +and +\fIsetitimer\fR() +are unspecified. +.SH "RETURN VALUE" +If there is a previous +\fIalarm\fR() +request with time remaining, +\fIalarm\fR() +shall return a non-zero value that is the number of seconds until the +previous request would have generated a SIGALRM signal. Otherwise, +\fIalarm\fR() +shall return 0. +.SH ERRORS +The +\fIalarm\fR() +function is always successful, and no return value is reserved to +indicate an error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfork\fR() +function clears pending alarms in the child process. A new process +image created by one of the +.IR exec +functions inherits the time left to an alarm signal in the +image of the old process. +.P +Application developers should note that the type of the argument +.IR seconds +and the return value of +\fIalarm\fR() +is +.BR unsigned . +That means that a Strictly Conforming POSIX System Interfaces +Application cannot pass a value greater than the minimum guaranteed +value for +{UINT_MAX}, +which the ISO\ C standard +sets as 65\|535, and any application passing a larger value is +restricting its portability. A different type was considered, but +historical implementations, including those with a 16-bit +.BR int +type, consistently use either +.BR unsigned +or +.BR int . +.P +Application developers should be aware of possible interactions when +the same process uses both the +\fIalarm\fR() +and +\fIsleep\fR() +functions. +.SH RATIONALE +Many historical implementations (including Version 7 +and System V) allow an alarm to occur up to a second early. +Other implementations allow alarms up to half a second or one clock +tick early or do not +allow them to occur early at all. The latter is considered most +appropriate, since it gives the most predictable behavior, especially +since the signal can always be delayed for an indefinite amount of time +due to scheduling. Applications can thus choose the +.IR seconds +argument as the minimum amount of time they wish to have elapse before +the signal. +.P +The term ``realtime'' here and elsewhere (\c +\fIsleep\fR(), +\fItimes\fR()) +is intended to mean ``wall clock'' time as common English usage, and +has nothing to do with ``realtime operating systems''. It is in +contrast to \fIvirtual time\fP, which could be misinterpreted if just +\fItime\fP were used. +.P +In some implementations, including 4.3 BSD, very large values of the +.IR seconds +argument are silently rounded down to an implementation-specific maximum +value. This maximum is large enough (to the order of several months) +that the effect is not noticeable. +.P +There were two possible choices for alarm generation in multi-threaded +applications: generation for the calling thread or generation for the +process. The first option would not have been particularly useful +since the alarm state is maintained on a per-process basis and the +alarm that is established by the last invocation of +\fIalarm\fR() +is the only one that would be active. +.P +Furthermore, allowing generation of an asynchronous signal for a thread +would have introduced an exception to the overall signal model. This +requires a compelling reason in order to be justified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIpause\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/alphasort.3p b/upstream/archlinux/man3p/alphasort.3p new file mode 100644 index 00000000..3d595266 --- /dev/null +++ b/upstream/archlinux/man3p/alphasort.3p @@ -0,0 +1,268 @@ +'\" et +.TH ALPHASORT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +alphasort, scandir +\(em scan a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int alphasort(const struct dirent **\fId1\fP, const struct dirent **\fId2\fP); +int scandir(const char *\fIdir\fP, struct dirent ***\fInamelist\fP, + int (*\fIsel\fP)(const struct dirent *), + int (*\fIcompar\fP)(const struct dirent **, const struct dirent **)); +.fi +.SH DESCRIPTION +The +\fIalphasort\fR() +function can be used as the comparison function for the +\fIscandir\fR() +function to sort the directory entries, +.IR d1 +and +.IR d2 , +into alphabetical order. Sorting happens as if by calling the +\fIstrcoll\fR() +function on the +.IR d_name +element of the +.BR dirent +structures passed as the two parameters. If the +\fIstrcoll\fR() +function fails, the return value of +\fIalphasort\fR() +is unspecified. +.P +The +\fIalphasort\fR() +function shall not change the setting of +.IR errno +if successful. Since no return value is reserved to indicate an error, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIalphasort\fR(), +then check +.IR errno . +.P +The +\fIscandir\fR() +function shall scan the directory +.IR dir , +calling the function referenced by +.IR sel +on each directory entry. Entries for which the function referenced by +.IR sel +returns non-zero shall be stored in strings allocated as if by +a call to +\fImalloc\fR(), +and sorted as if by a call to +\fIqsort\fR() +with the comparison function +.IR compar , +except that +.IR compar +need not provide total ordering. The strings are collected in +array +.IR namelist +which shall be allocated as if by a call to +\fImalloc\fR(). +If +.IR sel +is a null pointer, all entries shall be selected. +If the comparison function +.IR compar +does not provide total ordering, the order in which the directory +entries are stored is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the +\fIalphasort\fR() +function shall return an integer greater than, equal to, or less than 0, +according to whether the name of the directory entry pointed to by +.IR d1 +is lexically greater than, equal to, or less than the directory pointed +to by +.IR d2 +when both are interpreted as appropriate to the current locale. There +is no return value reserved to indicate an error. +.P +Upon successful completion, the +\fIscandir\fR() +function shall return the number of entries in the array and a pointer +to the array through the parameter +.IR namelist . +Otherwise, the +\fIscandir\fR() +function shall return \-1. +.SH ERRORS +The +\fIscandir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for the component of the path prefix of +.IR dir +or read permission is denied for +.IR dir . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR dir +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR dir +does not name an existing directory or +.IR dir +is an empty string. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENOTDIR +A component of +.IR dir +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EOVERFLOW +One of the values to be returned or passed to a callback function cannot +be represented correctly. +.P +The +\fIscandir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR dir +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +An example to print the files in the current directory: +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +struct dirent **namelist; +int i,n; +.P + n = scandir(".", &namelist, 0, alphasort); + if (n < 0) + perror("scandir"); + else { + for (i = 0; i < n; i++) { + printf("%s\en", namelist[i]->d_name); + free(namelist[i]); + } + } + free(namelist); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +If +.IR dir +contains filenames that do not form character strings, or which contain +characters outside the domain of the collating sequence of the current +locale, the +\fIalphasort\fR() +function need not provide a total ordering. This condition is not possible +if all filenames within the directory consist only of characters from +the portable filename character set. +.P +The +\fIscandir\fR() +function may allocate dynamic storage during its operation. If +\fIscandir\fR() +is forcibly terminated, such as by +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +being executed by the function pointed to by +.IR sel +or +.IR compar , +or by an interrupt routine, +\fIscandir\fR() +does not have a chance to free that storage, so it remains permanently +allocated. A safe way to handle interrupts is to store the fact that +an interrupt has occurred, then wait until +\fIscandir\fR() +returns to act on the interrupt. +.P +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIscandir\fR(), +this is +.IR namelist +(including all of the individual strings in +.IR namelist ). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIqsort\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/asctime.3p b/upstream/archlinux/man3p/asctime.3p new file mode 100644 index 00000000..5e930122 --- /dev/null +++ b/upstream/archlinux/man3p/asctime.3p @@ -0,0 +1,199 @@ +'\" et +.TH ASCTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +asctime, +asctime_r +\(em convert date and time to a string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *asctime(const struct tm *\fItimeptr\fP); +char *asctime_r(const struct tm *restrict \fItm\fP, char *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +For +\fIasctime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIasctime\fR() +function shall convert the broken-down time in the structure pointed +to by +.IR timeptr +into a string in the form: +.sp +.RS 4 +.nf + +Sun Sep 16 01:03:52 1973\en\e0 +.fi +.P +.RE +.P +using the equivalent of the following algorithm: +.sp +.RS 4 +.nf + +char *asctime(const struct tm *timeptr) +{ + static char wday_name[7][3] = { + "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" + }; + static char mon_name[12][3] = { + "Jan", "Feb", "Mar", "Apr", "May", "Jun", + "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" + }; + static char result[26]; +.P + sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\en", + wday_name[timeptr->tm_wday], + mon_name[timeptr->tm_mon], + timeptr->tm_mday, timeptr->tm_hour, + timeptr->tm_min, timeptr->tm_sec, + 1900 + timeptr->tm_year); + return result; +} +.fi +.P +.RE +.P +However, the behavior is undefined if \fItimeptr\fR\->\fItm_wday\fR or +\fItimeptr\fR\->\fItm_mon\fR are not within the normal ranges as +defined in +.IR , +or if \fItimeptr\fR\->\fItm_year\fR exceeds +{INT_MAX}\-1990, +or if the above algorithm would attempt to generate more than 26 bytes +of output (including the terminating null). +.P +The +.BR tm +structure is defined in the +.IR +header. +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of type +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIasctime\fR() +function need not be thread-safe. +.P +The +\fIasctime_r\fR() +function shall convert the broken-down time in the structure pointed to +by +.IR tm +into a string (of the same form as that returned by +\fIasctime\fR(), +and with the same undefined behavior when input or output is out of +range) that is placed in the user-supplied buffer pointed to by +.IR buf +(which shall contain at least 26 bytes) and then return +.IR buf . +.SH "RETURN VALUE" +Upon successful completion, +\fIasctime\fR() +shall return a pointer to the string. +If the function is unsuccessful, it shall return NULL. +.P +Upon successful completion, +\fIasctime_r\fR() +shall return a pointer to a character string containing the date and +time. This string is pointed to by the argument +.IR buf . +If the function is unsuccessful, it shall return NULL. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are included only for compatibility with older +implementations. They have undefined behavior if the resulting string +would be too long, so the use of these functions should be +discouraged. On implementations that do not detect output string +length overflow, it is possible to overflow the output buffers in such +a way as to cause applications to fail, or possible system security +violations. Also, these functions do not support localized date and +time formats. To avoid these problems, applications should use +\fIstrftime\fR() +to generate strings from broken-down times. +.P +Values for the broken-down time structure can be obtained by calling +\fIgmtime\fR() +or +\fIlocaltime\fR(). +.P +The +\fIasctime_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.SH RATIONALE +The standard developers decided to mark the +\fIasctime\fR() +and +\fIasctime_r\fR() +functions obsolescent even though +\fIasctime\fR() +is in the ISO\ C standard due to the possibility of buffer overflow. The ISO\ C standard +also provides the +\fIstrftime\fR() +function which can be used to avoid these problems. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/asin.3p b/upstream/archlinux/man3p/asin.3p new file mode 100644 index 00000000..e498e8d8 --- /dev/null +++ b/upstream/archlinux/man3p/asin.3p @@ -0,0 +1,158 @@ +'\" et +.TH ASIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +asin, +asinf, +asinl +\(em arc sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +double asin(double \fIx\fP); +float asinf(float \fIx\fP); +long double asinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc sine of +their argument +.IR x . +The value of +.IR x +should be in the range [\-1,1]. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc sine +of +.IR x , +in the range [\-\(*p/2,\(*p/2] radians. +.P +For finite values of +.IR x +not in the range [\-1,1], a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIasin\fR(), +\fIasinf\fR(), +and +\fIasinl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and is not in the range [\-1,1], +or is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/asinh.3p b/upstream/archlinux/man3p/asinh.3p new file mode 100644 index 00000000..9cfc7319 --- /dev/null +++ b/upstream/archlinux/man3p/asinh.3p @@ -0,0 +1,125 @@ +'\" et +.TH ASINH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +asinh, +asinhf, +asinhl +\(em inverse hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double asinh(double \fIx\fP); +float asinhf(float \fIx\fP); +long double asinhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the inverse hyperbolic sine of their +argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the inverse +hyperbolic sine of their argument. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIasinh\fR(), +\fIasinhf\fR(), +and +\fIasinhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIsinh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/asinl.3p b/upstream/archlinux/man3p/asinl.3p new file mode 100644 index 00000000..b1f23c99 --- /dev/null +++ b/upstream/archlinux/man3p/asinl.3p @@ -0,0 +1,40 @@ +'\" et +.TH ASINL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +asinl +\(em arc sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double asinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIasin\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/assert.3p b/upstream/archlinux/man3p/assert.3p new file mode 100644 index 00000000..05195dcd --- /dev/null +++ b/upstream/archlinux/man3p/assert.3p @@ -0,0 +1,94 @@ +'\" et +.TH ASSERT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +assert +\(em insert program diagnostics +.SH SYNOPSIS +.LP +.nf +#include +.P +void assert(scalar \fIexpression\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIassert\fR() +macro shall insert diagnostics into programs; it shall expand to a +.BR void +expression. When it is executed, if +.IR expression +(which shall have a +.BR scalar +type) is false (that is, compares equal to 0), +\fIassert\fR() +shall write information about the particular call that failed on +.IR stderr +and shall call +\fIabort\fR(). +.P +The information written about the call that failed shall include the +text of the argument, the name of the source file, the source file line +number, and the name of the enclosing function; the latter are, +respectively, the values of the preprocessing macros _\|_FILE_\|_ and +_\|_LINE_\|_ +and of the identifier _\|_func_\|_. +.P +Forcing a definition of the name NDEBUG, +either from the compiler command line or with the preprocessor control +statement +.BR #define +NDEBUG ahead of the +.BR #include +.IR +statement, shall stop assertions from being compiled into the program. +.SH "RETURN VALUE" +The +\fIassert\fR() +macro shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabort\fR\^(\|)", +.IR "\fIstdin\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atan.3p b/upstream/archlinux/man3p/atan.3p new file mode 100644 index 00000000..90cff838 --- /dev/null +++ b/upstream/archlinux/man3p/atan.3p @@ -0,0 +1,133 @@ +'\" et +.TH ATAN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atan, +atanf, +atanl +\(em arc tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +double atan(double \fIx\fP); +float atanf(float \fIx\fP); +long double atanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc tangent of +their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc +tangent of +.IR x +in the range [\-\(*p/2,\(*p/2] radians. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, \(+-\(*p/2 shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIatan\fR(), +\fIatanf\fR(), +and +\fIatanl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatan2\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atan2.3p b/upstream/archlinux/man3p/atan2.3p new file mode 100644 index 00000000..f958aaf6 --- /dev/null +++ b/upstream/archlinux/man3p/atan2.3p @@ -0,0 +1,241 @@ +'\" et +.TH ATAN2 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atan2, +atan2f, +atan2l +\(em arc tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double atan2(double \fIy\fP, double \fIx\fP); +float atan2f(float \fIy\fP, float \fIx\fP); +long double atan2l(long double \fIy\fP, long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the principal value of the arc tangent of +.IR y /\c +.IR x , +using the signs of both arguments to determine the quadrant of the +return value. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the arc +tangent of +.IR y /\c +.IR x +in the range [\-\(*p,\(*p] radians. +.P +If +.IR y +is \(+-0 and +.IR x +is < 0, \(+-\(*p shall be returned. +.P +If +.IR y +is \(+-0 and +.IR x +is > 0, \(+-0 shall be returned. +.P +If +.IR y +is < 0 and +.IR x +is \(+-0, \-\(*p/2 shall be returned. +.P +If +.IR y +is > 0 and +.IR x +is \(+-0, \(*p/2 shall be returned. +.P +If +.IR x +is 0, a pole error shall not occur. +.P +If either +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If the correct value would cause underflow, a range error may occur, and +\fIatan\fR(), +\fIatan2f\fR(), +and +\fIatan2l\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If the IEC 60559 Floating-Point option is supported, +.IR y /\c +.IR x +should be returned. +.P +If +.IR y +is \(+-0 and +.IR x +is \-0, \(+-\(*p shall be returned. +.P +If +.IR y +is \(+-0 and +.IR x +is +0, \(+-0 shall be returned. +.P +For finite values of \(+-\c +.IR y +> 0, if +.IR x +is \-Inf, \(+-\(*p shall be returned. +.P +For finite values of \(+-\c +.IR y +> 0, if +.IR x +is +Inf, \(+-0 shall be returned. +.P +For finite values of +.IR x , +if +.IR y +is \(+-Inf, \(+-\(*p/2 shall be returned. +.P +If +.IR y +is \(+-Inf and +.IR x +is \-Inf, \(+-3\(*p/4 shall be returned. +.P +If +.IR y +is \(+-Inf and +.IR x +is +Inf, \(+-\(*p/4 shall be returned. +.P +If both arguments are 0, a domain error shall not occur. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Converting Cartesian to Polar Coordinates System" +.P +The function below uses +\fIatan2\fR() +to convert a 2d vector expressed in cartesian coordinates +(\fIx\fR,\fIy\fR) to the polar coordinates (\fIrho\fR,\fItheta\fR). +There are other ways to compute the angle +.IR theta , +using +\fIasin\fR() +\fIacos\fR(), +or +\fIatan\fR(). +However, +\fIatan2\fR() +presents here two advantages: +.IP " *" 4 +The angle's quadrant is automatically determined. +.IP " *" 4 +The singular cases (0,\fIy\fR) are taken into account. +.P +Finally, this example uses +\fIhypot\fR() +rather than +\fIsqrt\fR() +since it is better for special cases; see +\fIhypot\fR() +for more information. +.sp +.RS 4 +.nf + +#include +.P +void +cartesian_to_polar(const double x, const double y, + double *rho, double *theta + ) +{ + *rho = hypot (x,y); /* better than sqrt(x*x+y*y) */ + *theta = atan2 (y,x); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIacos\fR\^(\|)", +.IR "\fIasin\fR\^(\|)", +.IR "\fIatan\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIhypot\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsqrt\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atanf.3p b/upstream/archlinux/man3p/atanf.3p new file mode 100644 index 00000000..71602da4 --- /dev/null +++ b/upstream/archlinux/man3p/atanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH ATANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atanf +\(em arc tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +float atanf(float \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIatan\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atanh.3p b/upstream/archlinux/man3p/atanh.3p new file mode 100644 index 00000000..ab632b51 --- /dev/null +++ b/upstream/archlinux/man3p/atanh.3p @@ -0,0 +1,176 @@ +'\" et +.TH ATANH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atanh, +atanhf, +atanhl +\(em inverse hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double atanh(double \fIx\fP); +float atanhf(float \fIx\fP); +long double atanhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the inverse hyperbolic tangent of their +argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the inverse +hyperbolic tangent of their argument. +.P +If +.IR x +is \(+-1, a pole error shall occur, and +\fIatanh\fR(), +\fIatanhf\fR(), +and +\fIatanhl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.P +For finite |\fIx\fR|>1, a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIatanh\fR(), +\fIatanhf\fR(), +and +\fIatanhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is finite and not in the range [\-1,1], +or is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The +.IR x +argument is \(+-1. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fItanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atanl.3p b/upstream/archlinux/man3p/atanl.3p new file mode 100644 index 00000000..edf953b5 --- /dev/null +++ b/upstream/archlinux/man3p/atanl.3p @@ -0,0 +1,40 @@ +'\" et +.TH ATANL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atanl +\(em arc tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double atanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIatan\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atexit.3p b/upstream/archlinux/man3p/atexit.3p new file mode 100644 index 00000000..ec568bc4 --- /dev/null +++ b/upstream/archlinux/man3p/atexit.3p @@ -0,0 +1,133 @@ +'\" et +.TH ATEXIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atexit +\(em register a function to run at process termination +.SH SYNOPSIS +.LP +.nf +#include +.P +int atexit(void (*\fIfunc\fP)(void)); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIatexit\fR() +function shall register the function pointed to by +.IR func , +to be called without arguments at normal program termination. At normal +program termination, all functions registered by the +\fIatexit\fR() +function shall be called, in the reverse order of their registration, +except that a function is called after any previously registered +functions that had already been called at the time it was registered. +Normal termination occurs either by a call to +\fIexit\fR() +or a return from +\fImain\fR(). +.P +At least 32 functions can be registered with +\fIatexit\fR(). +.P +After a successful call to any of the +.IR exec +functions, any functions previously registered by +\fIatexit\fR() +shall no longer be registered. +.SH "RETURN VALUE" +Upon successful completion, +\fIatexit\fR() +shall return 0; otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The functions registered by a call to +\fIatexit\fR() +must return to ensure that all registered functions are called. +.P +The application should call +\fIsysconf\fR() +to obtain the value of +{ATEXIT_MAX}, +the number of functions that can be registered. There is no way for an +application to tell how many functions have already been registered +with +\fIatexit\fR(). +.P +Since the behavior is undefined if the +\fIexit\fR() +function is called more than once, portable applications calling +\fIatexit\fR() +must ensure that the +\fIexit\fR() +function is not called at normal process termination when all functions +registered by the +\fIatexit\fR() +function are called. +.P +All functions registered by the +\fIatexit\fR() +function are called at normal process termination, which occurs by a +call to the +\fIexit\fR() +function or a return from +\fImain\fR() +or on the last thread termination, when the behavior is as if the +implementation called +\fIexit\fR() +with a zero argument at thread termination time. +.P +If, at normal process termination, a function registered by the +\fIatexit\fR() +function is called and a portable application needs to stop further +\fIexit\fR() +processing, it must call the +\fI_exit\fR() +function or the +\fI_Exit\fR() +function or one of the functions which cause abnormal process +termination. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atof.3p b/upstream/archlinux/man3p/atof.3p new file mode 100644 index 00000000..30a045f1 --- /dev/null +++ b/upstream/archlinux/man3p/atof.3p @@ -0,0 +1,87 @@ +'\" et +.TH ATOF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atof +\(em convert a string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double atof(const char *\fIstr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The call +.IR atof ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf + +strtod(\fIstr\fP,(char **)NULL), +.fi +.P +.RE +.P +except that the handling of errors may differ. If the value cannot be +represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIatof\fR() +function shall return the converted value if the value can be +represented. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIatof\fR() +function is subsumed by +\fIstrtod\fR() +but is retained because it is used extensively in existing code. If the +number is not known to be in range, +\fIstrtod\fR() +should be used because +\fIatof\fR() +is not required to perform any error checking. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atoi.3p b/upstream/archlinux/man3p/atoi.3p new file mode 100644 index 00000000..ef0e2600 --- /dev/null +++ b/upstream/archlinux/man3p/atoi.3p @@ -0,0 +1,110 @@ +'\" et +.TH ATOI "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atoi +\(em convert a string to an integer +.SH SYNOPSIS +.LP +.nf +#include +.P +int atoi(const char *\fIstr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The call +.IR atoi ( str ) +shall be equivalent to: +.sp +.RS 4 +.nf + +(int) strtol(str, (char **)NULL, 10) +.fi +.P +.RE +.P +except that the handling of errors may differ. If the value cannot be +represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIatoi\fR() +function shall return the converted value if the value can be +represented. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Converting an Argument" +.P +The following example checks for proper usage of the program. If there +is an argument and the decimal conversion of this argument (obtained +using +\fIatoi\fR()) +is greater than 0, then the program has a valid number of minutes to +wait for an event. +.sp +.RS 4 +.nf + +#include +#include +\&... +int minutes_to_event; +\&... +if (argc < 2 || ((minutes_to_event = atoi (argv[1]))) <= 0) { + fprintf(stderr, "Usage: %s minutes\en", argv[0]); exit(1); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIatoi\fR() +function is subsumed by +\fIstrtol\fR() +but is retained because it is used extensively in existing code. If the +number is not known to be in range, +\fIstrtol\fR() +should be used because +\fIatoi\fR() +is not required to perform any error checking. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/atol.3p b/upstream/archlinux/man3p/atol.3p new file mode 100644 index 00000000..c0b6126a --- /dev/null +++ b/upstream/archlinux/man3p/atol.3p @@ -0,0 +1,98 @@ +'\" et +.TH ATOL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +atol, +atoll +\(em convert a string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long atol(const char *\fInptr\fP); +long long atoll(const char *\fInptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +Except as noted below, the call +.IR atol ( nptr ) +shall be equivalent to: +.sp +.RS 4 +.nf + +strtol(nptr, (char **)NULL, 10) +.fi +.P +.RE +.P +Except as noted below, the call to +.IR atoll ( nptr ) +shall be equivalent to: +.sp +.RS 4 +.nf + +strtoll(nptr, (char **)NULL, 10) +.fi +.P +.RE +.P +The handling of errors may differ. If the value cannot be +represented, the behavior is undefined. +.SH "RETURN VALUE" +These functions shall return the converted value if the value can be +represented. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the number is not known to be in range, +\fIstrtol\fR() +or +\fIstrtoll\fR() +should be used because +\fIatol\fR() +and +\fIatoll\fR() +are not required to perform any error checking. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/basename.3p b/upstream/archlinux/man3p/basename.3p new file mode 100644 index 00000000..3aff3029 --- /dev/null +++ b/upstream/archlinux/man3p/basename.3p @@ -0,0 +1,166 @@ +'\" et +.TH BASENAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +basename +\(em return the last component of a pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +char *basename(char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIbasename\fR() +function shall take the pathname pointed to by +.IR path +and return a pointer to the final component of the pathname, deleting +any trailing +.BR '/' +characters. +.P +If the string pointed to by +.IR path +consists entirely of the +.BR '/' +character, +\fIbasename\fR() +shall return a pointer to the string +.BR \(dq/\(dq . +If the string pointed to by +.IR path +is exactly +.BR \(dq//\(dq , +it is implementation-defined whether +.BR '/' +or +.BR \(dq//\(dq +is returned. +.P +If +.IR path +is a null pointer or points to an empty string, +\fIbasename\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +.P +The +\fIbasename\fR() +function may modify the string pointed to by +.IR path , +and may return a pointer to internal storage. The returned pointer +might be invalidated or the storage might be overwritten by a +subsequent call to +\fIbasename\fR(). +The returned pointer might also be invalidated if the calling +thread is terminated. +.P +The +\fIbasename\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIbasename\fR() +function shall return a pointer to the final component of +.IR path . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using basename(\|)" +.P +The following program fragment returns a pointer to the value +.IR lib , +which is the base name of +.BR /usr/lib . +.sp +.RS 4 +.nf + +#include +\&... +char name[] = "/usr/lib"; +char *base; +.P +base = basename(name); +\&... +.fi +.P +.RE +.SS "Sample Input and Output Strings for the basename(\|) and dirname(\|) Functions and the basename and dirname Utilities" +.S -1 +.TS +center box tab(!); +cB | cB | cB | cB | cB | cB +cB | cB | cB | cB | cB | cB +cB | cB | cB | cB | cB | cB +cB | cB | cB | cB | cB | cB +lf51 | lf51 | lf51 | lf51 | lf51 | lf5. +basename(\|)!!!basename!Output!Output +and dirname(\|)!String!String!and dirname!Written by!Written by +Functions path!Returned by!Returned by!Utilities!basename!dirname +Argument!basename(\|)!dirname(\|)!string Operand!Utility!Utility +_ +"usr"!"usr"!"."!usr!usr!. +_ +"usr/"!"usr"!"."!usr/!usr!. +_ +""!"."!"."!""!. \fRor empty string\fR!. +_ +"/"!"/"!"/"!/!/!/ +_ +"//"!"/" \fRor\fR "//"!"/" \fRor\fR "//"!//!/ \fRor\fR //!/ \fRor\fR // +_ +"///"!"/"!"/"!///!/!/ +_ +"/usr/"!"usr"!"/"!/usr/!usr!/ +_ +"/usr/lib"!"lib"!"/usr"!/usr/lib!lib!/usr +_ +"//usr//lib//"!"lib"!"//usr"!//usr//lib//!lib!//usr +_ +"/home//dwc//!"test"!"/home//dwc"!/home//dwc//!test!/home//dwc +test"!!!test +.TE +.S +1 +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdirname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIbasename\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/bind.3p b/upstream/archlinux/man3p/bind.3p new file mode 100644 index 00000000..10c97057 --- /dev/null +++ b/upstream/archlinux/man3p/bind.3p @@ -0,0 +1,294 @@ +'\" et +.TH BIND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +bind +\(em bind a name to a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int bind(int \fIsocket\fP, const struct sockaddr *\fIaddress\fP, + socklen_t \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIbind\fR() +function shall assign a local socket address +.IR address +to a socket identified by descriptor +.IR socket +that has no local socket address assigned. Sockets created with the +\fIsocket\fR() +function are initially unnamed; they are identified only by their +address family. +.P +The +\fIbind\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the file descriptor of the socket to be bound. +.IP "\fIaddress\fR" 12 +Points to a +.BR sockaddr +structure containing the address to be bound to the socket. The length +and format of the address depend on the address family of the socket. +.IP "\fIaddress_len\fR" 12 +Specifies the length of the +.BR sockaddr +structure pointed to by the +.IR address +argument. +.P +The socket specified by +.IR socket +may require the process to have appropriate privileges to use the +\fIbind\fR() +function. +.P +If the address family of the socket is AF_UNIX and the pathname in +.IR address +names a symbolic link, +\fIbind\fR() +shall fail and set +.IR errno +to +.BR [EADDRINUSE] . +.P +If the socket address cannot be assigned immediately and O_NONBLOCK is +set for the file descriptor for the socket, +\fIbind\fR() +shall fail and set +.IR errno +to +.BR [EINPROGRESS] , +but the assignment request shall not be aborted, and the assignment +shall be completed asynchronously. Subsequent calls to +\fIbind\fR() +for the same socket, before the assignment is completed, shall fail +and set +.IR errno +to +.BR [EALREADY] . +.P +When the assignment has been performed asynchronously, +\fIpselect\fR(), +\fIselect\fR(), +and +\fIpoll\fR() +shall indicate that the file descriptor for the socket is ready for +reading and writing. +.SH "RETURN VALUE" +Upon successful completion, +\fIbind\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIbind\fR() +function shall fail if: +.TP +.BR EADDRINUSE +The specified address is already in use. +.TP +.BR EADDRNOTAVAIL +.br +The specified address is not available from the local machine. +.TP +.BR EAFNOSUPPORT +.br +The specified address is not a valid address for the address family of +the specified socket. +.TP +.BR EALREADY +An assignment request is already in progress for the specified socket. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINPROGRESS +O_NONBLOCK is set for the file descriptor for the socket and the +assignment cannot be immediately performed; the assignment shall be +performed asynchronously. +.TP +.BR EINVAL +The socket is already bound to an address, and the protocol does not +support binding to a new address; or the socket has been shut down. +.TP +.BR ENOBUFS +Insufficient resources were available to complete the call. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The socket type of the specified socket does not support binding to an +address. +.P +If the address family of the socket is AF_UNIX, then +\fIbind\fR() +shall fail if: +.TP +.BR EACCES +A component of the path prefix denies search permission, or the +requested name requires writing in a directory with a mode that denies +write permission. +.TP +.BR EDESTADDRREQ " or " EISDIR +.br +The +.IR address +argument is a null pointer. +.TP +.BR EIO +An I/O error occurred. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix of the pathname in +.IR address +does not name an existing file or the pathname is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The pathname in +.IR address +contains at least one non-\c + +character and ends with one or more trailing + +characters. If the pathname without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in +.IR address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in +.IR address +contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The name would reside on a read-only file system. +.P +The +\fIbind\fR() +function may fail if: +.TP +.BR EACCES +The specified address is protected and the current user does not have +permission to bind to it. +.TP +.BR EINVAL +The +.IR address_len +argument is not a valid length for the address family. +.TP +.BR EISCONN +The socket is already connected. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following code segment shows how to create a socket and +bind it to a name in the AF_UNIX domain. +.sp +.RS 4 +.nf + +#define MY_SOCK_PATH "/somepath" +.P +int sfd; +struct sockaddr_un my_addr; +.P +sfd = socket(AF_UNIX, SOCK_STREAM, 0); +if (sfd == -1) + /* Handle error */; +.P +memset(&my_addr, \(aq\e0\(aq, sizeof(struct sockaddr_un)); + /* Clear structure */ +my_addr.sun_family = AF_UNIX; +strncpy(my_addr.sun_path, MY_SOCK_PATH, sizeof(my_addr.sun_path) -1); +.P +if (bind(sfd, (struct sockaddr *) &my_addr, + sizeof(struct sockaddr_un)) == -1) + /* Handle error */; +.fi +.P +.RE +.SH "APPLICATION USAGE" +An application program can retrieve the assigned socket name with the +\fIgetsockname\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/bsearch.3p b/upstream/archlinux/man3p/bsearch.3p new file mode 100644 index 00000000..22326544 --- /dev/null +++ b/upstream/archlinux/man3p/bsearch.3p @@ -0,0 +1,195 @@ +'\" et +.TH BSEARCH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +bsearch +\(em binary search a sorted table +.SH SYNOPSIS +.LP +.nf +#include +.P +void *bsearch(const void *\fIkey\fP, const void *\fIbase\fP, size_t \fInel\fP, + size_t \fIwidth\fP, int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIbsearch\fR() +function shall search an array of +.IR nel +objects, the initial element of which is pointed to by +.IR base , +for an element that matches the object pointed to by +.IR key . +The size of each element in the array is specified by +.IR width . +If the +.IR nel +argument has the value zero, the comparison function pointed to by +.IR compar +shall not be called and no match shall be found. +.P +The comparison function pointed to by +.IR compar +shall be called with two arguments that point to the +.IR key +object and to an array element, in that order. +.P +The application shall ensure that the comparison function pointed to by +.IR compar +does not alter the contents of the array. The implementation may +reorder elements of the array between calls to the comparison function, +but shall not alter the contents of any individual element. +.P +The implementation shall ensure that the first argument is always a +pointer to the key. +.P +When the same objects (consisting of width bytes, irrespective of their +current positions in the array) are passed more than once to the +comparison function, the results shall be consistent with one another. +That is, the same object shall always compare the same way with the +key. +.P +The application shall ensure that the function returns an integer less +than, equal to, or greater than 0 if the +.IR key +object is considered, respectively, to be less than, to match, or to be +greater than the array element. The application shall ensure that the +array consists of all the elements that compare less than, all the +elements that compare equal to, and all the elements that compare +greater than the +.IR key +object, in that order. +.SH "RETURN VALUE" +The +\fIbsearch\fR() +function shall return a pointer to a matching member of the array, or a +null pointer if no match is found. If two or more members compare +equal, which member is returned is unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The example below searches a table containing pointers to nodes +consisting of a string and its length. The table is ordered +alphabetically on the string in the node pointed to by each entry. +.P +The code fragment below reads in strings and either finds the +corresponding node and prints out the string and its length, or prints +an error message. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +#define\ TABSIZE 1000 +.P +struct node { /* These are stored in the table. */ + char *string; + int length; +}; +struct node table[TABSIZE]; /* Table to be searched. */ + . + . + . +{ + struct node *node_ptr, node; + /* Routine to compare 2 nodes. */ + int node_compare(const void *, const void *); + . + . + . + while (scanf("%ms", &node.string) != EOF) { + node_ptr = (struct node *)bsearch((void *)(&node), + (void *)table, TABSIZE, + sizeof(struct node), node_compare); + if (node_ptr != NULL) { + (void)printf("string = %20s, length = %d\en", + node_ptr->string, node_ptr->length); + } else { + (void)printf("not found: %s\en", node.string); + } + free(node.string); + } +} +/* + This routine compares two nodes based on an + alphabetical ordering of the string field. +*/ +int +node_compare(const void *node1, const void *node2) +{ + return strcoll(((const struct node *)node1)->string, + ((const struct node *)node2)->string); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The pointers to the key and the element at the base of the table should +be of type pointer-to-element. +.P +The comparison function need not compare every byte, so arbitrary data +may be contained in the elements in addition to the values being +compared. +.P +In practice, the array is usually sorted according to the comparison +function. +.SH RATIONALE +The requirement that the second argument (hereafter referred to as +.IR p ) +to the comparison function is a pointer to an element of the array +implies that for every call all of the following expressions are +non-zero: +.sp +.RS 4 +.nf + +( (char *)p - (char *)base ) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhcreate\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)", +.IR "\fIqsort\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/btowc.3p b/upstream/archlinux/man3p/btowc.3p new file mode 100644 index 00000000..54122eab --- /dev/null +++ b/upstream/archlinux/man3p/btowc.3p @@ -0,0 +1,87 @@ +'\" et +.TH BTOWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +btowc +\(em single byte to wide character conversion +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t btowc(int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIbtowc\fR() +function shall determine whether +.IR c +constitutes a valid (one-byte) character in the initial shift state. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.SH "RETURN VALUE" +The +\fIbtowc\fR() +function shall return WEOF if +.IR c +has the value EOF or if +.BR "(unsigned char)" +.IR c +does not constitute a valid (one-byte) character in the initial shift +state. Otherwise, it shall return the wide-character representation of +that character. +.P +In the POSIX locale, +\fIbtowc\fR() +shall not return WEOF if +.IR c +has a value in the range 0 to 255 inclusive. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwctob\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cabs.3p b/upstream/archlinux/man3p/cabs.3p new file mode 100644 index 00000000..e9d0ed70 --- /dev/null +++ b/upstream/archlinux/man3p/cabs.3p @@ -0,0 +1,66 @@ +'\" et +.TH CABS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cabs, +cabsf, +cabsl +\(em return a complex absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +double cabs(double complex \fIz\fP); +float cabsf(float complex \fIz\fP); +long double cabsl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex absolute value (also called +norm, modulus, or magnitude) of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex absolute value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cacos.3p b/upstream/archlinux/man3p/cacos.3p new file mode 100644 index 00000000..e10292ae --- /dev/null +++ b/upstream/archlinux/man3p/cacos.3p @@ -0,0 +1,71 @@ +'\" et +.TH CACOS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cacos, +cacosf, +cacosl +\(em complex arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cacos(double complex \fIz\fP); +float complex cacosf(float complex \fIz\fP); +long double complex cacosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc cosine of +.IR z , +with branch cuts outside the interval [\-1,\ +1] along the real +axis. +.SH "RETURN VALUE" +These functions shall return the complex arc cosine value, in the range +of a strip mathematically unbounded along the imaginary axis and in the +interval [0,\ \(*p] along the real axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIccos\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cacosh.3p b/upstream/archlinux/man3p/cacosh.3p new file mode 100644 index 00000000..9f26c16d --- /dev/null +++ b/upstream/archlinux/man3p/cacosh.3p @@ -0,0 +1,71 @@ +'\" et +.TH CACOSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cacosh, +cacoshf, +cacoshl +\(em complex arc hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cacosh(double complex \fIz\fP); +float complex cacoshf(float complex \fIz\fP); +long double complex cacoshl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc hyperbolic cosine of +.IR z , +with a branch cut at values less than 1 along the real axis. +.SH "RETURN VALUE" +These functions shall return the complex arc hyperbolic cosine value, +in the range of a half-strip of non-negative values along the real axis +and in the interval [\-\fIi\fR\(*p,\ +\fIi\fR\(*p] along the +imaginary axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIccosh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cacosl.3p b/upstream/archlinux/man3p/cacosl.3p new file mode 100644 index 00000000..47260c76 --- /dev/null +++ b/upstream/archlinux/man3p/cacosl.3p @@ -0,0 +1,40 @@ +'\" et +.TH CACOSL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cacosl +\(em complex arc cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex cacosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcacos\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/calloc.3p b/upstream/archlinux/man3p/calloc.3p new file mode 100644 index 00000000..96add968 --- /dev/null +++ b/upstream/archlinux/man3p/calloc.3p @@ -0,0 +1,116 @@ +'\" et +.TH CALLOC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +calloc +\(em a memory allocator +.SH SYNOPSIS +.LP +.nf +#include +.P +void *calloc(size_t \fInelem\fP, size_t \fIelsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIcalloc\fR() +function shall allocate unused space for an array of +.IR nelem +elements each of whose size in bytes is +.IR elsize . +The space shall be initialized to all bits 0. +.P +The order and contiguity of storage allocated by successive calls to +\fIcalloc\fR() +is unspecified. The pointer returned if the allocation succeeds shall +be suitably aligned so that it may be assigned to a pointer to any type +of object and then used to access such an object or an array of such +objects in the space allocated (until the space is explicitly freed or +reallocated). Each such allocation shall yield a pointer to an object +disjoint from any other object. The pointer returned shall point to the +start (lowest byte address) of the allocated space. If the space cannot +be allocated, a null pointer shall be returned. If the size of the +space requested is 0, the behavior is implementation-defined: either a +null pointer shall be returned, or the behavior shall be as if the +size were some non-zero value, except that the behavior is undefined +if the returned pointer is used to access an object. +.SH "RETURN VALUE" +Upon successful completion with both +.IR nelem +and +.IR elsize +non-zero, +\fIcalloc\fR() +shall return a pointer to the allocated space. If either +.IR nelem +or +.IR elsize +is 0, then either: +.IP " *" 4 +A null pointer shall be returned +and +.IR errno +may be set to an implementation-defined value, +or +.IP " *" 4 +A pointer to the allocated space shall be returned. The application +shall ensure that the pointer is not used to access an object. +.P +Otherwise, it shall return a null pointer +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIcalloc\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +There is now no requirement for the implementation to support the +inclusion of +.IR . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/carg.3p b/upstream/archlinux/man3p/carg.3p new file mode 100644 index 00000000..907e8c22 --- /dev/null +++ b/upstream/archlinux/man3p/carg.3p @@ -0,0 +1,71 @@ +'\" et +.TH CARG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +carg, +cargf, +cargl +\(em complex argument functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double carg(double complex \fIz\fP); +float cargf(float complex \fIz\fP); +long double cargl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the argument (also called phase angle) of +.IR z , +with a branch cut along the negative real axis. +.SH "RETURN VALUE" +These functions shall return the value of the argument in the interval +[\-\(*p,\ +\(*p]. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcimag\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/casin.3p b/upstream/archlinux/man3p/casin.3p new file mode 100644 index 00000000..b6b5a1a9 --- /dev/null +++ b/upstream/archlinux/man3p/casin.3p @@ -0,0 +1,71 @@ +'\" et +.TH CASIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +casin, +casinf, +casinl +\(em complex arc sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex casin(double complex \fIz\fP); +float complex casinf(float complex \fIz\fP); +long double complex casinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc sine of +.IR z , +with branch cuts outside the interval [\-1,\ +1] along the real +axis. +.SH "RETURN VALUE" +These functions shall return the complex arc sine value, in the range +of a strip mathematically unbounded along the imaginary axis and in the +interval [\-\(*p/2,\ +\(*p/2] along the real axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcsin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/casinh.3p b/upstream/archlinux/man3p/casinh.3p new file mode 100644 index 00000000..cbf84af6 --- /dev/null +++ b/upstream/archlinux/man3p/casinh.3p @@ -0,0 +1,72 @@ +'\" et +.TH CASINH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +casinh, +casinhf, +casinhl +\(em complex arc hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex casinh(double complex \fIz\fP); +float complex casinhf(float complex \fIz\fP); +long double complex casinhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc hyperbolic sine of +.IR z , +with branch cuts outside the interval [\-\fIi\fR,\ +\fIi\fR] along +the imaginary axis. +.SH "RETURN VALUE" +These functions shall return the complex arc hyperbolic sine value, in +the range of a strip mathematically unbounded along the real axis and +in the interval [\-\fIi\fR\(*p/2,\ +\fIi\fR\(*p/2] along the +imaginary axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcsinh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/casinl.3p b/upstream/archlinux/man3p/casinl.3p new file mode 100644 index 00000000..c5078e47 --- /dev/null +++ b/upstream/archlinux/man3p/casinl.3p @@ -0,0 +1,40 @@ +'\" et +.TH CASINL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +casinl +\(em complex arc sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex casinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcasin\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/catan.3p b/upstream/archlinux/man3p/catan.3p new file mode 100644 index 00000000..72e6caff --- /dev/null +++ b/upstream/archlinux/man3p/catan.3p @@ -0,0 +1,71 @@ +'\" et +.TH CATAN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +catan, +catanf, +catanl +\(em complex arc tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex catan(double complex \fIz\fP); +float complex catanf(float complex \fIz\fP); +long double complex catanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc tangent of +.IR z , +with branch cuts outside the interval [\-\fIi\fR,\ +\fIi\fR] along +the imaginary axis. +.SH "RETURN VALUE" +These functions shall return the complex arc tangent value, in the +range of a strip mathematically unbounded along the imaginary axis and +in the interval [\-\(*p/2,\ +\(*p/2] along the real axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/catanh.3p b/upstream/archlinux/man3p/catanh.3p new file mode 100644 index 00000000..337e72d9 --- /dev/null +++ b/upstream/archlinux/man3p/catanh.3p @@ -0,0 +1,72 @@ +'\" et +.TH CATANH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +catanh, +catanhf, +catanhl +\(em complex arc hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex catanh(double complex \fIz\fP); +float complex catanhf(float complex \fIz\fP); +long double complex catanhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex arc hyperbolic tangent of +.IR z , +with branch cuts outside the interval [\-1,\ +1] along the real +axis. +.SH "RETURN VALUE" +These functions shall return the complex arc hyperbolic tangent value, +in the range of a strip mathematically unbounded along the real axis +and in the interval [\-\fIi\fR\(*p/2,\ +\fIi\fR\(*p/2] along the +imaginary axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/catanl.3p b/upstream/archlinux/man3p/catanl.3p new file mode 100644 index 00000000..e000b2b0 --- /dev/null +++ b/upstream/archlinux/man3p/catanl.3p @@ -0,0 +1,40 @@ +'\" et +.TH CATANL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +catanl +\(em complex arc tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex catanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcatan\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/catclose.3p b/upstream/archlinux/man3p/catclose.3p new file mode 100644 index 00000000..2612ef9f --- /dev/null +++ b/upstream/archlinux/man3p/catclose.3p @@ -0,0 +1,79 @@ +'\" et +.TH CATCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +catclose +\(em close a message catalog descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int catclose(nl_catd \fIcatd\fP); +.fi +.SH DESCRIPTION +The +\fIcatclose\fR() +function shall close the message catalog identified by +.IR catd . +If a file descriptor is used to implement the type +.BR nl_catd , +that file descriptor shall be closed. +.SH "RETURN VALUE" +Upon successful completion, +\fIcatclose\fR() +shall return 0; otherwise, \-1 shall be returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIcatclose\fR() +function may fail if: +.TP +.BR EBADF +The catalog descriptor is not valid. +.TP +.BR EINTR +The +\fIcatclose\fR() +function was interrupted by a signal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatgets\fR\^(\|)", +.IR "\fIcatopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/catgets.3p b/upstream/archlinux/man3p/catgets.3p new file mode 100644 index 00000000..725de7f3 --- /dev/null +++ b/upstream/archlinux/man3p/catgets.3p @@ -0,0 +1,127 @@ +'\" et +.TH CATGETS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +catgets +\(em read a program message +.SH SYNOPSIS +.LP +.nf +#include +.P +char *catgets(nl_catd \fIcatd\fP, int \fIset_id\fP, int \fImsg_id\fP, const char *\fIs\fP); +.fi +.SH DESCRIPTION +The +\fIcatgets\fR() +function shall attempt to read message +.IR msg_id , +in set +.IR set_id , +from the message catalog identified by +.IR catd . +The +.IR catd +argument is a message catalog descriptor returned from an earlier call +to +\fIcatopen\fR(). +The results are undefined if +.IR catd +is not a value returned by +\fIcatopen\fR() +for a message catalog still open in the process. The +.IR s +argument points to a default message string which shall be returned by +\fIcatgets\fR() +if it cannot retrieve the identified message. +.P +The +\fIcatgets\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If the identified message is retrieved successfully, +\fIcatgets\fR() +shall return a pointer to an internal buffer area containing the +null-terminated message string. If the call is unsuccessful for any +reason, +.IR s +shall be returned and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIcatgets\fR() +function shall fail if: +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR ENOMSG +The message identified by +.IR set_id +and +.IR msg_id +is not in the message catalog. +.P +The +\fIcatgets\fR() +function may fail if: +.TP +.BR EBADF +The +.IR catd +argument is not a valid message catalog descriptor open for reading. +.TP +.BR EBADMSG +The message identified by +.IR set_id +and +.IR msg_id +in the specified message catalog did not satisfy implementation-defined +security criteria. +.TP +.BR EINVAL +The message catalog identified by +.IR catd +is corrupted. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatclose\fR\^(\|)", +.IR "\fIcatopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/catopen.3p b/upstream/archlinux/man3p/catopen.3p new file mode 100644 index 00000000..44f9b320 --- /dev/null +++ b/upstream/archlinux/man3p/catopen.3p @@ -0,0 +1,208 @@ +'\" et +.TH CATOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +catopen +\(em open a message catalog +.SH SYNOPSIS +.LP +.nf +#include +.P +nl_catd catopen(const char *\fIname\fP, int \fIoflag\fP); +.fi +.SH DESCRIPTION +The +\fIcatopen\fR() +function shall open a message catalog and return a message catalog +descriptor. The +.IR name +argument specifies the name of the message catalog to be opened. If +.IR name +contains a +.BR '/' , +then +.IR name +specifies a pathname for the message catalog. Otherwise, the +environment variable +.IR NLSPATH +is used with +.IR name +substituted for the +.BR %N +conversion specification (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables"); +if +.IR NLSPATH +exists in the environment when the process starts, then if the process +has appropriate privileges, the behavior of +\fIcatopen\fR() +is undefined. If +.IR NLSPATH +does not exist in the environment, or if a message catalog cannot be +found in any of the components specified by +.IR NLSPATH , +then an implementation-defined default path shall be used. This default +may be affected by the setting of +.IR LC_MESSAGES +if the value of +.IR oflag +is NL_CAT_LOCALE, or the +.IR LANG +environment variable if +.IR oflag +is 0. +.P +A message catalog descriptor shall remain valid in a process until that +process closes it, or a successful call to one of the +.IR exec +functions. A change in the setting of the +.IR LC_MESSAGES +category may invalidate existing open catalogs. +.P +If a file descriptor is used to implement message catalog descriptors, +the FD_CLOEXEC flag shall be set; see +.IR . +.P +If the value of the +.IR oflag +argument is 0, the +.IR LANG +environment variable is used to locate the catalog without regard to +the +.IR LC_MESSAGES +category. If the +.IR oflag +argument is NL_CAT_LOCALE, the +.IR LC_MESSAGES +category is used to locate the message catalog (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables"). +.SH "RETURN VALUE" +Upon successful completion, +\fIcatopen\fR() +shall return a message catalog descriptor for use on subsequent calls to +\fIcatgets\fR() +and +\fIcatclose\fR(). +Otherwise, +\fIcatopen\fR() +shall return (\c +.BR nl_catd ) +\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIcatopen\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for the component of the path prefix of the +message catalog or read permission is denied for the message catalog. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.TP +.BR ENOENT +The message catalog does not exist or the +.IR name +argument points to an empty string. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENOTDIR +A component of the path prefix of the message catalog names an existing +file that is neither a directory nor a symbolic link to a directory, +or the pathname of the message catalog contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Some implementations of +\fIcatopen\fR() +use +\fImalloc\fR() +to allocate space for internal buffer areas. The +\fIcatopen\fR() +function may fail if there is insufficient storage space available to +accommodate these buffers. +.P +Conforming applications must assume that message catalog descriptors are +not valid after a call to one of the +.IR exec +functions. +.P +Application developers should be aware that guidelines for the location +of message catalogs have not yet been developed. Therefore they should +take care to avoid conflicting with catalogs used by other applications +and the standard utilities. +.P +To be sure that messages produced by an application running with +appropriate privileges cannot be used by an attacker setting an +unexpected value for +.IR NLSPATH +in the environment to confuse a system administrator, such +applications should use pathnames containing a +.BR '/' +to get defined behavior when using +\fIcatopen\fR() +to open a message catalog. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatclose\fR\^(\|)", +.IR "\fIcatgets\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP", +.IR "\fB\fP", +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cbrt.3p b/upstream/archlinux/man3p/cbrt.3p new file mode 100644 index 00000000..86771e19 --- /dev/null +++ b/upstream/archlinux/man3p/cbrt.3p @@ -0,0 +1,83 @@ +'\" et +.TH CBRT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cbrt, +cbrtf, +cbrtl +\(em cube root functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double cbrt(double \fIx\fP); +float cbrtf(float \fIx\fP); +long double cbrtl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the real cube root of their argument +.IR x . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the cube root +of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +For some applications, a true cube root function, which returns +negative results for negative arguments, is more appropriate than +.IR pow (\c +.IR x , +1.0/3.0), which returns a NaN for +.IR x +less than 0. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ccos.3p b/upstream/archlinux/man3p/ccos.3p new file mode 100644 index 00000000..79449299 --- /dev/null +++ b/upstream/archlinux/man3p/ccos.3p @@ -0,0 +1,67 @@ +'\" et +.TH CCOS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ccos, +ccosf, +ccosl +\(em complex cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ccos(double complex \fIz\fP); +float complex ccosf(float complex \fIz\fP); +long double complex ccosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex cosine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex cosine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcacos\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ccosh.3p b/upstream/archlinux/man3p/ccosh.3p new file mode 100644 index 00000000..476c2461 --- /dev/null +++ b/upstream/archlinux/man3p/ccosh.3p @@ -0,0 +1,67 @@ +'\" et +.TH CCOSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ccosh, +ccoshf, +ccoshl +\(em complex hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ccosh(double complex \fIz\fP); +float complex ccoshf(float complex \fIz\fP); +long double complex ccoshl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex hyperbolic cosine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex hyperbolic cosine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcacosh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ccosl.3p b/upstream/archlinux/man3p/ccosl.3p new file mode 100644 index 00000000..7d93d783 --- /dev/null +++ b/upstream/archlinux/man3p/ccosl.3p @@ -0,0 +1,40 @@ +'\" et +.TH CCOSL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ccosl +\(em complex cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex ccosl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIccos\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ceil.3p b/upstream/archlinux/man3p/ceil.3p new file mode 100644 index 00000000..4d9509d3 --- /dev/null +++ b/upstream/archlinux/man3p/ceil.3p @@ -0,0 +1,103 @@ +'\" et +.TH CEIL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ceil, +ceilf, +ceill +\(em ceiling value function +.SH SYNOPSIS +.LP +.nf +#include +.P +double ceil(double \fIx\fP); +float ceilf(float \fIx\fP); +long double ceill(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the smallest integral value not less than +.IR x . +.SH "RETURN VALUE" +The result shall have the same sign as +.IR x . +.P +Upon successful completion, +\fIceil\fR(), +\fIceilf\fR(), +and +\fIceill\fR() +shall return the smallest integral value not less than +.IR x , +expressed as a type +.BR double , +.BR float , +or +.BR "long double" , +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfloor\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cexp.3p b/upstream/archlinux/man3p/cexp.3p new file mode 100644 index 00000000..7d6cd7c6 --- /dev/null +++ b/upstream/archlinux/man3p/cexp.3p @@ -0,0 +1,69 @@ +'\" et +.TH CEXP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cexp, +cexpf, +cexpl +\(em complex exponential functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cexp(double complex \fIz\fP); +float complex cexpf(float complex \fIz\fP); +long double complex cexpl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex exponent of +.IR z , +defined as \fIe\s-3\uz\d\s+3\fR. +.SH "RETURN VALUE" +These functions shall return the complex exponential value of +.IR z . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cfgetispeed.3p b/upstream/archlinux/man3p/cfgetispeed.3p new file mode 100644 index 00000000..f65a113d --- /dev/null +++ b/upstream/archlinux/man3p/cfgetispeed.3p @@ -0,0 +1,128 @@ +'\" et +.TH CFGETISPEED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cfgetispeed +\(em get input baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +speed_t cfgetispeed(const struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fIcfgetispeed\fR() +function shall extract the input baud rate from the +.BR termios +structure to which the +.IR termios_p +argument points. +.P +This function shall return exactly the value in the +.BR termios +data structure, without interpretation. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfgetispeed\fR() +shall return a value of type +.BR speed_t +representing the input baud rate. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The term ``baud'' is used historically here, but is not technically +correct. This is properly ``bits per second'', which may not be the +same as baud. However, the term is used because of the historical +usage and understanding. +.P +The +\fIcfgetospeed\fR(), +\fIcfgetispeed\fR(), +\fIcfsetospeed\fR(), +and +\fIcfsetispeed\fR() +functions do not take arguments as numbers, but rather as symbolic +names. There are two reasons for this: +.IP " 1." 4 +Historically, numbers were not used because of the way the rate was +stored in the data structure. This is retained even though a +function is now used. +.IP " 2." 4 +More importantly, only a limited set of possible rates is at all +portable, and this constrains the application to that set. +.P +There is nothing to prevent an implementation accepting as an extension +a number (such as 126), and since the encoding of the Bxxx symbols is +not specified, this can be done to avoid introducing ambiguity. +.P +Setting the input baud rate to zero was a mechanism to allow for split +baud rates. Clarifications in this volume of POSIX.1\(hy2017 have made it possible to determine +whether split rates are supported and to support them without having to +treat zero as a special case. Since this functionality is also +confusing, it has been declared obsolescent. +The 0 argument referred to is the literal constant 0, not the symbolic +constant B0. This volume of POSIX.1\(hy2017 does not preclude B0 from being defined as the value +0; in fact, implementations would likely benefit from the two being +equivalent. This volume of POSIX.1\(hy2017 does not fully specify whether the previous +\fIcfsetispeed\fR() +value is retained after a +\fItcgetattr\fR() +as the actual value or as zero. Therefore, conforming applications should +always set both the input speed and output speed when setting either. +.P +In historical implementations, the baud rate information is +traditionally kept in +.BR c_cflag . +Applications should be written to presume that this might be the case +(and thus not blindly copy +.BR c_cflag ), +but not to rely on it in case it is in some other field of the +structure. Setting the +.BR c_cflag +field absolutely after setting a baud rate is a non-portable action +because of this. In general, the unused parts of the flag fields might +be used by the implementation and should not be blindly copied from the +descriptions of one terminal device to another. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cfgetospeed.3p b/upstream/archlinux/man3p/cfgetospeed.3p new file mode 100644 index 00000000..dccc3c4d --- /dev/null +++ b/upstream/archlinux/man3p/cfgetospeed.3p @@ -0,0 +1,77 @@ +'\" et +.TH CFGETOSPEED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cfgetospeed +\(em get output baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +speed_t cfgetospeed(const struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fIcfgetospeed\fR() +function shall extract the output baud rate from the +.BR termios +structure to which the +.IR termios_p +argument points. +.P +This function shall return exactly the value in the +.BR termios +data structure, without interpretation. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfgetospeed\fR() +shall return a value of type +.BR speed_t +representing the output baud rate. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIcfgetispeed\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cfsetispeed.3p b/upstream/archlinux/man3p/cfsetispeed.3p new file mode 100644 index 00000000..8603de21 --- /dev/null +++ b/upstream/archlinux/man3p/cfsetispeed.3p @@ -0,0 +1,96 @@ +'\" et +.TH CFSETISPEED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cfsetispeed +\(em set input baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +int cfsetispeed(struct termios *\fItermios_p\fP, speed_t \fIspeed\fP); +.fi +.SH DESCRIPTION +The +\fIcfsetispeed\fR() +function shall set the input baud rate stored in the structure pointed +to by +.IR termios_p +to +.IR speed. +.P +There shall be no effect on the baud rates set in the hardware until a +subsequent successful call to +\fItcsetattr\fR() +with the same +.BR termios +structure. Similarly, errors resulting from attempts to set baud rates +not supported by the terminal device need not be detected until the +\fItcsetattr\fR() +function is called. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfsetispeed\fR() +shall return 0; otherwise, \-1 shall be returned, and +.IR errno +may be set to indicate the error. +.SH ERRORS +The +\fIcfsetispeed\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR speed +value is not a valid baud rate. +.TP +.BR EINVAL +The value of +.IR speed +is outside the range of possible speed values as specified in +.IR . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIcfgetispeed\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetospeed\fR\^(\|)", +.IR "\fItcsetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cfsetospeed.3p b/upstream/archlinux/man3p/cfsetospeed.3p new file mode 100644 index 00000000..74d7c749 --- /dev/null +++ b/upstream/archlinux/man3p/cfsetospeed.3p @@ -0,0 +1,96 @@ +'\" et +.TH CFSETOSPEED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cfsetospeed +\(em set output baud rate +.SH SYNOPSIS +.LP +.nf +#include +.P +int cfsetospeed(struct termios *\fItermios_p\fP, speed_t \fIspeed\fP); +.fi +.SH DESCRIPTION +The +\fIcfsetospeed\fR() +function shall set the output baud rate stored in the structure pointed +to by +.IR termios_p +to +.IR speed . +.P +There shall be no effect on the baud rates set in the hardware until a +subsequent successful call to +\fItcsetattr\fR() +with the same +.BR termios +structure. Similarly, errors resulting from attempts to set baud rates +not supported by the terminal device need not be detected until the +\fItcsetattr\fR() +function is called. +.SH "RETURN VALUE" +Upon successful completion, +\fIcfsetospeed\fR() +shall return 0; otherwise, it shall return \-1 and +.IR errno +may be set to indicate the error. +.SH ERRORS +The +\fIcfsetospeed\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR speed +value is not a valid baud rate. +.TP +.BR EINVAL +The value of +.IR speed +is outside the range of possible speed values as specified in +.IR . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIcfgetispeed\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fIcfgetospeed\fR\^(\|)", +.IR "\fIcfsetispeed\fR\^(\|)", +.IR "\fItcsetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/chdir.3p b/upstream/archlinux/man3p/chdir.3p new file mode 100644 index 00000000..b4d0575d --- /dev/null +++ b/upstream/archlinux/man3p/chdir.3p @@ -0,0 +1,133 @@ +'\" et +.TH CHDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +chdir +\(em change working directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int chdir(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIchdir\fR() +function shall cause the directory named by the pathname pointed to +by the +.IR path +argument to become the current working directory; that is, the starting +point for path searches for pathnames not beginning with +.BR '/' . +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 shall +be returned, the current working directory shall remain unchanged, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIchdir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for any component of the pathname. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing directory or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the pathname names an existing file that is neither +a directory nor a symbolic link to a directory. +.P +The +\fIchdir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Working Directory" +.P +The following example makes the value pointed to by +.BR directory , +.BR /tmp , +the current working directory. +.sp +.RS 4 +.nf + +#include +\&... +char *directory = "/tmp"; +int ret; +.P +ret = chdir (directory); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIchdir\fR() +function only affects the working directory of the current process. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetcwd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/chmod.3p b/upstream/archlinux/man3p/chmod.3p new file mode 100644 index 00000000..13ea518e --- /dev/null +++ b/upstream/archlinux/man3p/chmod.3p @@ -0,0 +1,372 @@ +'\" et +.TH CHMOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +chmod, fchmodat +\(em change mode of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int chmod(const char *\fIpath\fP, mode_t \fImode\fP); +.P +#include +.P +int fchmodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIchmod\fR() +function shall change S_ISUID, S_ISGID, +S_ISVTX, +and the file permission bits of the file named by the pathname pointed +to by the +.IR path +argument to the corresponding bits in the +.IR mode +argument. The application shall ensure that the effective user ID +of the process matches the owner of the file or the process has +appropriate privileges in order to do this. +.P +S_ISUID, S_ISGID, +S_ISVTX, +and the file permission bits +are described in +.IR . +.P +If the calling process does not have appropriate privileges, and if the +group ID of the file does not match the effective group ID or one of +the supplementary group IDs and if the file is a regular file, bit +S_ISGID (set-group-ID on execution) in the file's mode shall be cleared +upon successful return from +\fIchmod\fR(). +.P +Additional implementation-defined restrictions may cause the S_ISUID +and S_ISGID bits in +.IR mode +to be ignored. +.P +Upon successful completion, +\fIchmod\fR() +shall mark for update the last file status change timestamp of the file. +.P +The +\fIfchmodat\fR() +function shall be equivalent to the +\fIchmod\fR() +function except in the case where +.IR path +specifies a relative path. In this case the file to be changed is +determined relative to the directory associated with the file +descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches +are permitted using the current permissions of the directory +underlying the file descriptor. If the access mode is +O_SEARCH, the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, then the mode of the symbolic link is changed. +.P +If +\fIfchmodat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used. If also +.IR flag +is zero, the behavior shall be identical to a call to +\fIchmod\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, no change to the +file mode occurs. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP +.BR EROFS +The named file resides on a read-only file system. +.P +The +\fIfchmodat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR EINVAL +The value of the +.IR mode +argument is invalid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +The +\fIfchmodat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is invalid. +.TP +.BR EOPNOTSUPP +The AT_SYMLINK_NOFOLLOW bit is set in the +.IR flag +argument, +.IR path +names a symbolic link, and the system does not support changing the +mode of a symbolic link. +.br +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting Read Permissions for User, Group, and Others" +.P +The following example sets read permissions for the owner, group, and +others. +.sp +.RS 4 +.nf + +#include +.P +const char *path; +\&... +chmod(path, S_IRUSR|S_IRGRP|S_IROTH); +.fi +.P +.RE +.SS "Setting Read, Write, and Execute Permissions for the Owner Only" +.P +The following example sets read, write, and execute permissions for the +owner, and no permissions for group and others. +.sp +.RS 4 +.nf + +#include +.P +const char *path; +\&... +chmod(path, S_IRWXU); +.fi +.P +.RE +.SS "Setting Different Permissions for Owner, Group, and Other" +.P +The following example sets owner permissions for CHANGEFILE to read, +write, and execute, group permissions to read and execute, and other +permissions to read. +.sp +.RS 4 +.nf + +#include +.P +#define CHANGEFILE "/etc/myfile" +\&... +chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); +.fi +.P +.RE +.SS "Setting and Checking File Permissions" +.P +The following example sets the file permission bits for a file named +.BR /home/cnd/mod1 , +then calls the +\fIstat\fR() +function to verify the permissions. +.sp +.RS 4 +.nf + +#include +#include +.P +int status; +struct stat buffer +\&... +chmod("/home/cnd/mod1", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH); +status = stat("/home/cnd/mod1", &buffer); +.fi +.P +.RE +.SH "APPLICATION USAGE" +In order to ensure that the S_ISUID and S_ISGID +bits are set, an application requiring this should use +\fIstat\fR() +after a successful +\fIchmod\fR() +to verify this. +.P +Any file descriptors currently open by any process on the file could +possibly become invalid if the mode of the file is changed to a value +which would deny access to that process. One situation where this could +occur is on a stateless file system. This behavior will not occur in a +conforming environment. +.SH RATIONALE +This volume of POSIX.1\(hy2017 specifies that the S_ISGID bit is cleared by +\fIchmod\fR() +on a regular file under certain conditions. This is specified on the +assumption that regular files may be executed, and the system should +prevent users from making executable +\fIsetgid\fR() +files perform with privileges that the caller does not have. On +implementations that support execution of other file types, the S_ISGID +bit should be cleared for those file types under the same +circumstances. +.P +Implementations that use the S_ISUID bit to indicate some other +function (for example, mandatory record locking) on non-executable +files need not clear this bit on writing. They should clear the bit +for executable files and any other cases where the bit grants special +powers to processes that change the file contents. Similar comments +apply to the S_ISGID bit. +.P +The purpose of the +\fIfchmodat\fR() +function is to enable changing the mode of files in directories other +than the current working directory without exposure to race conditions. +Any part of the path of a file could be changed in parallel to a call +to +\fIchmod\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfchmodat\fR() +function it can be guaranteed that the changed file is located relative +to the desired directory. Some implementations might allow changing +the mode of symbolic links. This is not supported by the interfaces in +the POSIX specification. Systems with such support provide an +interface named +.IR lchmod (\|). +To support such implementations +\fIfchmodat\fR() +has a +.IR flag +parameter. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccess\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfstatvfs\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/chown.3p b/upstream/archlinux/man3p/chown.3p new file mode 100644 index 00000000..bb4dd1b9 --- /dev/null +++ b/upstream/archlinux/man3p/chown.3p @@ -0,0 +1,336 @@ +'\" et +.TH CHOWN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +chown, fchownat +\(em change owner and group of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int chown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +.P +#include +.P +int fchownat(int \fIfd\fP, const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP, + int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIchown\fR() +function shall change the user and group ownership of a file. +.P +The +.IR path +argument points to a pathname naming a file. The user ID and group ID +of the named file shall be set to the numeric values contained in +.IR owner +and +.IR group , +respectively. +.P +Only processes with an effective user ID equal to the user ID of the +file or with appropriate privileges may change the ownership of a +file. If _POSIX_CHOWN_RESTRICTED is in effect for +.IR path : +.IP " *" 4 +Changing the user ID is restricted to processes with appropriate +privileges. +.IP " *" 4 +Changing the group ID is permitted to a process with an effective user +ID equal to the user ID of the file, but without appropriate +privileges, if and only if +.IR owner +is equal to the file's user ID or (\c +.BR uid_t )\-1 +and +.IR group +is equal either to the calling process' effective group ID or to one of +its supplementary group IDs. +.P +If the specified file is a regular file, one or more of the S_IXUSR, +S_IXGRP, or S_IXOTH bits of the file mode are set, and the process does +not have appropriate privileges, the set-user-ID (S_ISUID) and +set-group-ID (S_ISGID) bits of the file mode shall be cleared upon +successful return from +\fIchown\fR(). +If the specified file is a regular file, one or more of the S_IXUSR, +S_IXGRP, or S_IXOTH bits of the file mode are set, and the process has +appropriate privileges, it is implementation-defined whether the +set-user-ID and set-group-ID bits are altered. If the +\fIchown\fR() +function is successfully invoked on a file that is not a regular file +and one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of the file +mode are set, the set-user-ID and set-group-ID bits may be cleared. +.P +If +.IR owner +or +.IR group +is specified as (\c +.BR uid_t )\-1 +or (\c +.BR gid_t )\-1, +respectively, the corresponding ID of the file shall not be changed. +.P +Upon successful completion, +\fIchown\fR() +shall mark for update the last file status change timestamp of the +file, except that if +.IR owner +is (\c +.BR uid_t )\-1 +and +.IR group +is (\c +.BR gid_t )\-1, +the file status change timestamp need not be marked for update. +.P +The +\fIfchownat\fR() +function shall be equivalent to the +\fIchown\fR() +and +\fIlchown\fR() +functions except in the case where +.IR path +specifies a relative path. In this case the file to be changed is +determined relative to the directory associated with the file +descriptor +.IR fd +instead of the current working directory. If the access mode of +the open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, ownership of the symbolic link is changed. +.P +If +\fIfchownat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIchown\fR() +or +\fIlchown\fR() +respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit +is set in the +.IR flag +argument. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, no changes are +made in the user ID and group ID of the file. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID does not match the owner of the file, or the +calling process does not have appropriate privileges and +_POSIX_CHOWN_RESTRICTED indicates that such privilege is required. +.TP +.BR EROFS +The named file resides on a read-only file system. +.P +The +\fIfchownat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EIO +An I/O error occurred while reading or writing to the file system. +.TP +.BR EINTR +The +\fIchown\fR() +function was interrupted by a signal which was caught. +.TP +.BR EINVAL +The owner or group ID supplied is not a value supported by the +implementation. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.br +.P +The +\fIfchownat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Although +\fIchown\fR() +can be used on some implementations by the file owner to change the owner +and group to any desired values, the only portable use of this function +is to change the group of a file to the effective GID of the calling +process or to a member of its group set. +.SH RATIONALE +System III and System V allow a user to give away files; +that is, the owner of a file may change its user ID to anything. This +is a serious problem for implementations that are intended to meet +government security regulations. +Version 7 and 4.3 BSD permit only the superuser +to change the user ID of a file. Some government agencies (usually not +ones concerned directly with security) find this limitation too +confining. This volume of POSIX.1\(hy2017 uses \fImay\fP to permit secure implementations +while not disallowing System V. +.P +System III and System V allow the owner of a file to change the +group ID to anything. Version 7 permits only the superuser to change +the group ID of a file. +4.3 BSD permits the owner to change the group ID of a file +to its effective group ID +or to any of the groups in the list of supplementary group IDs, but to +no others. +.P +The POSIX.1\(hy1990 standard requires that the +\fIchown\fR() +function invoked by a non-appropriate privileged process clear the +S_ISGID and the S_ISUID bits for regular files, and permits them to be +cleared for other types of files. This is so that changes in +accessibility do not accidentally cause files to become security holes. +Unfortunately, requiring these bits to be cleared on non-executable +data files also clears the mandatory file locking bit (shared with +S_ISGID), which is an extension on many implementations (it first +appeared in System V). These bits should only be required to be +cleared on regular files that have one or more of their execute bits +set. +.P +The purpose of the +\fIfchownat\fR() +function is to enable changing ownership of files in directories other +than the current working directory without exposure to race +conditions. Any part of the path of a file could be changed in +parallel to a call to +\fIchown\fR() +or +\fIlchown\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIfchownat\fR() +function it can be guaranteed that the changed file is located relative +to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cimag.3p b/upstream/archlinux/man3p/cimag.3p new file mode 100644 index 00000000..d870e720 --- /dev/null +++ b/upstream/archlinux/man3p/cimag.3p @@ -0,0 +1,80 @@ +'\" et +.TH CIMAG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cimag, +cimagf, +cimagl +\(em complex imaginary functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double cimag(double complex \fIz\fP); +float cimagf(float complex \fIz\fP); +long double cimagl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the imaginary part of +.IR z . +.SH "RETURN VALUE" +These functions shall return the imaginary part value (as a real). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For a variable +.IR z +of complex type: +.sp +.RS 4 +.nf + +z == creal(z) + cimag(z)*I +.fi +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/clearerr.3p b/upstream/archlinux/man3p/clearerr.3p new file mode 100644 index 00000000..cdb5ef53 --- /dev/null +++ b/upstream/archlinux/man3p/clearerr.3p @@ -0,0 +1,75 @@ +'\" et +.TH CLEARERR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clearerr +\(em clear indicators on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void clearerr(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIclearerr\fR() +function shall clear the end-of-file and error indicators for the +stream to which +.IR stream +points. +.P +The +\fIclearerr\fR() +function shall not change the setting of +.IR errno +if +.IR stream +is valid. +.SH "RETURN VALUE" +The +\fIclearerr\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/clock.3p b/upstream/archlinux/man3p/clock.3p new file mode 100644 index 00000000..b2c22065 --- /dev/null +++ b/upstream/archlinux/man3p/clock.3p @@ -0,0 +1,107 @@ +'\" et +.TH CLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clock +\(em report CPU time used +.SH SYNOPSIS +.LP +.nf +#include +.P +clock_t clock(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIclock\fR() +function shall return the implementation's best approximation to the +processor time used by the process since the beginning of an +implementation-defined era related only to the process invocation. +.SH "RETURN VALUE" +To determine the time in seconds, the value returned by +\fIclock\fR() +should be divided by the value of the macro CLOCKS_PER_SEC. +CLOCKS_PER_SEC is defined to be one million in +.IR . +If the processor time used is not available or its value cannot be +represented, the function shall return the value (\c +.BR clock_t )\-1. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +In programming environments where +.BR clock_t +is a 32-bit integer type and CLOCKS_PER_SEC is one million, +\fIclock\fR() +will start failing in less than 36 minutes of processor time for +signed +.BR clock_t , +or 72 minutes for unsigned +.BR clock_t . +Applications intended to be portable to such environments should use +\fItimes\fR() +instead (or +\fIclock_gettime\fR() +with CLOCK_PROCESS_CPUTIME_ID, if supported). +.P +In order to measure the time spent in a program, +\fIclock\fR() +should be called at the start of the program and its return value +subtracted from the value returned by subsequent calls. The value +returned by +\fIclock\fR() +is defined for compatibility across systems that have clocks with +different resolutions. The resolution on any particular system need +not be to microsecond accuracy. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/clock_getcpuclockid.3p b/upstream/archlinux/man3p/clock_getcpuclockid.3p new file mode 100644 index 00000000..3a42dd8d --- /dev/null +++ b/upstream/archlinux/man3p/clock_getcpuclockid.3p @@ -0,0 +1,100 @@ +'\" et +.TH CLOCK_GETCPUCLOCKID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clock_getcpuclockid +\(em access a process CPU-time clock +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_getcpuclockid(pid_t \fIpid\fP, clockid_t *\fIclock_id\fP); +.fi +.SH DESCRIPTION +The +\fIclock_getcpuclockid\fR() +function shall return the clock ID of the CPU-time clock of the process +specified by +.IR pid . +If the process described by +.IR pid +exists and the calling process has permission, the clock ID of this +clock shall be returned in +.IR clock_id . +.P +If +.IR pid +is zero, the +\fIclock_getcpuclockid\fR() +function shall return the clock ID of the CPU-time clock of the process +making the call, in +.IR clock_id . +.P +The conditions under which one process has permission to obtain the +CPU-time clock ID of other processes are implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, +\fIclock_getcpuclockid\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIclock_getcpuclockid\fR() +function shall fail if: +.TP +.BR EPERM +The requesting process does not have permission to access the CPU-time +clock for the process. +.P +The +\fIclock_getcpuclockid\fR() +function may fail if: +.TP +.BR ESRCH +No process can be found corresponding to the process specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIclock_getcpuclockid\fR() +function is part of the Process CPU-Time Clocks option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/clock_getres.3p b/upstream/archlinux/man3p/clock_getres.3p new file mode 100644 index 00000000..76be2f97 --- /dev/null +++ b/upstream/archlinux/man3p/clock_getres.3p @@ -0,0 +1,286 @@ +'\" et +.TH CLOCK_GETRES "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clock_getres, +clock_gettime, +clock_settime +\(em clock and timer functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_getres(clockid_t \fIclock_id\fP, struct timespec *\fIres\fP); +int clock_gettime(clockid_t \fIclock_id\fP, struct timespec *\fItp\fP); +int clock_settime(clockid_t \fIclock_id\fP, const struct timespec *\fItp\fP); +.fi +.SH DESCRIPTION +The +\fIclock_getres\fR() +function shall return the resolution of any clock. Clock resolutions +are implementation-defined and cannot be set by a process. If the +argument +.IR res +is not NULL, the resolution of the specified clock shall be stored in the +location pointed to by +.IR res . +If +.IR res +is NULL, the clock resolution is not returned. If the +.IR time +argument of +\fIclock_settime\fR() +is not a multiple of +.IR res , +then the value is truncated to a multiple of +.IR res . +.P +The +\fIclock_gettime\fR() +function shall return the current value +.IR tp +for the specified clock, +.IR clock_id . +.P +The +\fIclock_settime\fR() +function shall set the specified clock, +.IR clock_id , +to the value specified by +.IR tp . +Time values that are between two consecutive non-negative integer +multiples of the resolution of the specified clock shall be truncated +down to the smaller multiple of the resolution. +.P +A clock may be system-wide (that is, visible to all processes) or +per-process (measuring time that is meaningful only within a process). +All implementations shall support a +.IR clock_id +of CLOCK_REALTIME as defined in +.IR . +This clock represents the clock measuring real time for the system. +For this clock, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +represent the amount of time (in seconds and nanoseconds) since the +Epoch. An implementation may also support additional clocks. The +interpretation of time values for these clocks is unspecified. +.P +If the value of the CLOCK_REALTIME clock is set via +\fIclock_settime\fR(), +the new value of the clock shall be used to determine the time of +expiration for absolute time services based upon the CLOCK_REALTIME +clock. This applies to the time at which armed absolute timers expire. +If the absolute time requested at the invocation of such a time service +is before the new value of the clock, the time service shall expire +immediately as if the clock had reached the requested time normally. +.P +Setting the value of the CLOCK_REALTIME clock via +\fIclock_settime\fR() +shall have no effect on threads that are blocked waiting for a relative +time service based upon this clock, including the +\fInanosleep\fR() +function; nor on the expiration of relative timers based upon this +clock. Consequently, these time services shall expire when the +requested relative interval elapses, independently of the new or old +value of the clock. +.P +If the Monotonic Clock option is supported, all implementations shall +support a +.IR clock_id +of CLOCK_MONOTONIC defined in +.IR . +This clock represents the monotonic clock for the system. For this +clock, the value returned by +\fIclock_gettime\fR() +represents the amount of time (in seconds and nanoseconds) since an +unspecified point in the past (for example, system start-up time, or the +Epoch). This point does not change after system start-up time. The value +of the CLOCK_MONOTONIC clock cannot be set via +\fIclock_settime\fR(). +This function shall fail if it is invoked with a +.IR clock_id +argument of CLOCK_MONOTONIC. +.P +The effect of setting a clock via +\fIclock_settime\fR() +on armed per-process timers associated with a clock other than +CLOCK_REALTIME is implementation-defined. +.P +If the value of the CLOCK_REALTIME clock is set via +\fIclock_settime\fR(), +the new value of the clock shall be used to determine the time at which +the system shall awaken a thread blocked on an absolute +\fIclock_nanosleep\fR() +call based upon the CLOCK_REALTIME clock. If the absolute time +requested at the invocation of such a time service is before the new +value of the clock, the call shall return immediately as if the clock +had reached the requested time normally. +.P +Setting the value of the CLOCK_REALTIME clock via +\fIclock_settime\fR() +shall have no effect on any thread that is blocked on a relative +\fIclock_nanosleep\fR() +call. Consequently, the call shall return when the requested relative +interval elapses, independently of the new or old value of the clock. +.P +Appropriate privileges to set a particular clock are +implementation-defined. +.P +If _POSIX_CPUTIME is defined, implementations shall support clock ID +values obtained by invoking +\fIclock_getcpuclockid\fR(), +which represent the CPU-time clock of a given process. Implementations +shall also support the special +.BR clockid_t +value CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of +the calling process when invoking one of the +.IR clock_* (\|) +or +.IR timer_* (\|) +functions. For these clock IDs, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +represent the amount of execution time of the process associated with +the clock. Changing the value of a CPU-time clock via +\fIclock_settime\fR() +shall have no effect on the behavior of the sporadic server scheduling +policy (see +.IR "Scheduling Policies"). +.P +If _POSIX_THREAD_CPUTIME is defined, implementations shall support +clock ID values obtained by invoking +\fIpthread_getcpuclockid\fR(), +which represent the CPU-time clock of a given thread. Implementations +shall also support the special +.BR clockid_t +value CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of +the calling thread when invoking one of the +.IR clock_* (\|) +or +.IR timer_* (\|) +functions. For these clock IDs, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +shall represent the amount of execution time of the thread associated +with the clock. Changing the value of a CPU-time clock via +\fIclock_settime\fR() +shall have no effect on the behavior of the sporadic server scheduling +policy (see +.IR "Scheduling Policies"). +.SH "RETURN VALUE" +A return value of 0 shall indicate that the call succeeded. A return +value of \-1 shall indicate that an error occurred, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIclock_getres\fR(), +\fIclock_gettime\fR(), +and +\fIclock_settime\fR() +functions shall fail if: +.TP +.BR EINVAL +The +.IR clock_id +argument does not specify a known clock. +.P +The +\fIclock_gettime\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The number of seconds will not fit in an object of type +.BR time_t . +.P +The +\fIclock_settime\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR tp +argument to +\fIclock_settime\fR() +is outside the range for the given clock ID. +.TP +.BR EINVAL +The +.IR tp +argument specified a nanosecond value less than zero or greater than or +equal to 1\|000 million. +.TP +.BR EINVAL +The value of the +.IR clock_id +argument is CLOCK_MONOTONIC. +.P +The +\fIclock_settime\fR() +function may fail if: +.TP +.BR EPERM +The requesting process does not have appropriate privileges +to set the specified clock. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Note that the absolute value of the monotonic clock is meaningless +(because its origin is arbitrary), and thus there is no need to set it. +Furthermore, realtime applications can rely on the fact that the value +of this clock is never set and, therefore, that time intervals measured +with this clock will not be affected by calls to +\fIclock_settime\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "Scheduling Policies", +.IR "\fIclock_getcpuclockid\fR\^(\|)", +.IR "\fIclock_nanosleep\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/clock_nanosleep.3p b/upstream/archlinux/man3p/clock_nanosleep.3p new file mode 100644 index 00000000..341ed3a4 --- /dev/null +++ b/upstream/archlinux/man3p/clock_nanosleep.3p @@ -0,0 +1,267 @@ +'\" et +.TH CLOCK_NANOSLEEP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clock_nanosleep +\(em high resolution sleep with specifiable clock +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_nanosleep(clockid_t \fIclock_id\fP, int \fIflags\fP, + const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP); +.fi +.SH DESCRIPTION +If the flag TIMER_ABSTIME +is not set in the +.IR flags +argument, the +\fIclock_nanosleep\fR() +function shall cause the current thread to be suspended from execution +until either the time interval specified by the +.IR rqtp +argument has elapsed, or a signal is delivered to the calling thread +and its action is to invoke a signal-catching function, or the process +is terminated. The clock used to measure the time shall be the clock +specified by +.IR clock_id . +.P +If the flag TIMER_ABSTIME is set in the +.IR flags +argument, the +\fIclock_nanosleep\fR() +function shall cause the current thread to be suspended from execution +until either the time value of the clock specified by +.IR clock_id +reaches the absolute time specified by the +.IR rqtp +argument, or a signal is delivered to the calling thread and its action +is to invoke a signal-catching function, or the process is terminated. +If, at the time of the call, the time value specified by +.IR rqtp +is less than or equal to the time value of the specified clock, then +\fIclock_nanosleep\fR() +shall return immediately and the calling process shall not be +suspended. +.P +The suspension time caused by this function may be longer than +requested because the argument value is rounded up to an integer +multiple of the sleep resolution, or because of the scheduling of other +activity by the system. But, except for the case of being interrupted +by a signal, the suspension time for the relative +\fIclock_nanosleep\fR() +function (that is, with the TIMER_ABSTIME flag not set) shall not be +less than the time interval specified by +.IR rqtp , +as measured by the corresponding clock. The suspension for the absolute +\fIclock_nanosleep\fR() +function (that is, with the TIMER_ABSTIME flag set) shall be in effect +at least until the value of the corresponding clock reaches the +absolute time specified by +.IR rqtp , +except for the case of being interrupted by a signal. +.P +The use of the +\fIclock_nanosleep\fR() +function shall have no effect on the action or blockage of any signal. +.P +The +\fIclock_nanosleep\fR() +function shall fail if the +.IR clock_id +argument refers to the CPU-time clock of the calling thread. It is +unspecified whether +.IR clock_id +values of other CPU-time clocks are allowed. +.SH "RETURN VALUE" +If the +\fIclock_nanosleep\fR() +function returns because the requested time has elapsed, its return +value shall be zero. +.P +If the +\fIclock_nanosleep\fR() +function returns because it has been interrupted by a signal, it shall +return the corresponding error value. For the relative +\fIclock_nanosleep\fR() +function, if the +.IR rmtp +argument is non-NULL, the +.BR timespec +structure referenced by it shall be updated to contain the amount of +time remaining in the interval (the requested time minus the time +actually slept). The +.IR rqtp +and +.IR rmtp +arguments can point to the same object. If the +.IR rmtp +argument is NULL, the remaining time is not returned. The absolute +\fIclock_nanosleep\fR() +function has no effect on the structure referenced by +.IR rmtp . +.P +If +\fIclock_nanosleep\fR() +fails, it shall return the corresponding error value. +.SH ERRORS +The +\fIclock_nanosleep\fR() +function shall fail if: +.TP +.BR EINTR +The +\fIclock_nanosleep\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR rqtp +argument specified a nanosecond value less than zero or greater than or +equal to 1\|000 million; or the TIMER_ABSTIME flag was specified in +flags and the +.IR rqtp +argument is outside the range for the clock specified by +.IR clock_id ; +or the +.IR clock_id +argument does not specify a known clock, or specifies the CPU-time +clock of the calling thread. +.TP +.BR ENOTSUP +The +.IR clock_id +argument specifies a clock for which +\fIclock_nanosleep\fR() +is not supported, such as a CPU-time clock. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Calling +\fIclock_nanosleep\fR() +with the value TIMER_ABSTIME not set in the +.IR flags +argument and with a +.IR clock_id +of CLOCK_REALTIME is equivalent to calling +\fInanosleep\fR() +with the same +.IR rqtp +and +.IR rmtp +arguments. +.SH RATIONALE +The +\fInanosleep\fR() +function specifies that the system-wide clock CLOCK_REALTIME is used to +measure the elapsed time for this time service. However, with the +introduction of the monotonic clock CLOCK_MONOTONIC a new relative +sleep function is needed to allow an application to take advantage of +the special characteristics of this clock. +.P +There are many applications in which a process needs to be suspended +and then activated multiple times in a periodic way; for example, to +poll the status of a non-interrupting device or to refresh a display +device. For these cases, it is known that precise periodic activation +cannot be achieved with a relative +\fIsleep\fR() +or +\fInanosleep\fR() +function call. Suppose, for example, a periodic process that is +activated at time +.IR T 0, +executes for a while, and then wants to suspend itself until time +.IR T 0+\c +.IR T , +the period being +.IR T . +If this process wants to use the +\fInanosleep\fR() +function, it must first call +\fIclock_gettime\fR() +to get the current time, then calculate the difference between the +current time and +.IR T 0+\c +.IR T +and, finally, call +\fInanosleep\fR() +using the computed interval. However, the process could be preempted by +a different process between the two function calls, and in this case +the interval computed would be wrong; the process would wake up later +than desired. This problem would not occur with the absolute +\fIclock_nanosleep\fR() +function, since only one function call would be necessary to suspend +the process until the desired time. In other cases, however, a relative +sleep is needed, and that is why both functionalities are required. +.P +Although it is possible to implement periodic processes using the +timers interface, this implementation would require the use of signals, +and the reservation of some signal numbers. In this regard, the reasons +for including an absolute version of the +\fIclock_nanosleep\fR() +function in POSIX.1\(hy2008 are the same as for the inclusion of the relative +\fInanosleep\fR(). +.P +It is also possible to implement precise periodic processes using +\fIpthread_cond_timedwait\fR(), +in which an absolute timeout is specified that takes effect if the +condition variable involved is never signaled. However, the use of this +interface is unnatural, and involves performing other operations on +mutexes and condition variables that imply an unnecessary overhead. +Furthermore, +\fIpthread_cond_timedwait\fR() +is not available in implementations that do not support threads. +.P +Although the interface of the relative and absolute versions of the new +high resolution sleep service is the same +\fIclock_nanosleep\fR() +function, the +.IR rmtp +argument is only used in the relative sleep. This argument is needed in +the relative +\fIclock_nanosleep\fR() +function to reissue the function call if it is interrupted by a signal, +but it is not needed in the absolute +\fIclock_nanosleep\fR() +function call; if the call is interrupted by a signal, the absolute +\fIclock_nanosleep\fR() +function can be invoked again with the same +.IR rqtp +argument used in the interrupted call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/clock_settime.3p b/upstream/archlinux/man3p/clock_settime.3p new file mode 100644 index 00000000..c1ecd241 --- /dev/null +++ b/upstream/archlinux/man3p/clock_settime.3p @@ -0,0 +1,40 @@ +'\" et +.TH CLOCK_SETTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clock_settime +\(em clock and timer functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int clock_settime(clockid_t \fIclock_id\fP, const struct timespec *\fItp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIclock_getres\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/clog.3p b/upstream/archlinux/man3p/clog.3p new file mode 100644 index 00000000..415fe333 --- /dev/null +++ b/upstream/archlinux/man3p/clog.3p @@ -0,0 +1,73 @@ +'\" et +.TH CLOG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clog, +clogf, +clogl +\(em complex natural logarithm functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex clog(double complex \fIz\fP); +float complex clogf(float complex \fIz\fP); +long double complex clogl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex natural (base +.IR e ) +logarithm of +.IR z , +with a branch cut along the negative real axis. +.SH "RETURN VALUE" +These functions shall return the complex natural logarithm value, in +the range of a strip mathematically unbounded along the real axis and +in the interval [\-\fIi\fR\(*p,\ +\fIi\fR\(*p] along the imaginary +axis. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcexp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/close.3p b/upstream/archlinux/man3p/close.3p new file mode 100644 index 00000000..8c880ec0 --- /dev/null +++ b/upstream/archlinux/man3p/close.3p @@ -0,0 +1,356 @@ +'\" et +.TH CLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +close +\(em close a file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int close(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIclose\fR() +function shall deallocate the file descriptor indicated by +.IR fildes . +To deallocate means to make the file descriptor available for return by +subsequent calls to +\fIopen\fR() +or other functions that allocate file descriptors. All outstanding +record locks owned by the process on the file associated with the file +descriptor shall be removed (that is, unlocked). +.P +If +\fIclose\fR() +is interrupted by a signal that is to be caught, it shall return +\-1 with +.IR errno +set to +.BR [EINTR] +and the state of +.IR fildes +is unspecified. If an I/O error occurred while reading from or writing +to the file system during +\fIclose\fR(), +it may return \-1 with +.IR errno +set to +.BR [EIO] ; +if this error is returned, the state of +.IR fildes +is unspecified. +.P +When all file descriptors associated with a pipe or FIFO special file +are closed, any data remaining in the pipe or FIFO shall be discarded. +.P +When all file descriptors associated with an open file description have +been closed, the open file description shall be freed. +.P +If the link count of the file is 0, when all file descriptors +associated with the file are closed, the space occupied by the file +shall be freed and the file shall no longer be accessible. +.P +If a STREAMS-based +.IR fildes +is closed and the calling process was previously registered to receive +a SIGPOLL signal +for events associated with that STREAM, the calling process shall be +unregistered for events associated with the STREAM. The last +\fIclose\fR() +for a STREAM shall cause the STREAM associated with +.IR fildes +to be dismantled. If O_NONBLOCK is not set and there have been no +signals posted for the STREAM, +and if there is data on the module's write queue, +\fIclose\fR() +shall wait for an unspecified time (for each module and driver) for +any output to drain before dismantling the STREAM. The time delay +can be changed via an I_SETCLTIME +\fIioctl\fR() +request. If the O_NONBLOCK flag is set, or if there are any pending +signals, +\fIclose\fR() +shall not wait for output to drain, and shall dismantle the STREAM +immediately. +.P +If the implementation supports STREAMS-based pipes, and +.IR fildes +is associated with one end of a pipe, the last +\fIclose\fR() +shall cause a hangup to occur on the other end of the pipe. In +addition, if the other end of the pipe has been named by +\fIfattach\fR(), +then the last +\fIclose\fR() +shall force the named end to be detached by +\fIfdetach\fR(). +If the named end has no open file descriptors associated with it and +gets detached, the STREAM associated with that end shall also be +dismantled. +.P +If +.IR fildes +refers to the master side of a pseudo-terminal, and this is the last +close, a SIGHUP signal shall be sent to the +controlling process, if any, for which the slave side of the +pseudo-terminal is the controlling terminal. It is unspecified whether +closing the master side of the pseudo-terminal flushes all queued input +and output. +.P +If +.IR fildes +refers to the slave side of a STREAMS-based pseudo-terminal, a +zero-length message may be sent to the master. +.P +When there is an outstanding cancelable asynchronous I/O operation +against +.IR fildes +when +\fIclose\fR() +is called, that I/O operation may be canceled. An I/O operation that +is not canceled completes as if the +\fIclose\fR() +operation had not yet occurred. All operations that are not canceled +shall complete as if the +\fIclose\fR() +blocked until the operations completed. The +\fIclose\fR() +operation itself need not block awaiting such I/O completion. Whether +any I/O operation is canceled, and which I/O operation may be +canceled upon +\fIclose\fR(), +is implementation-defined. +.P +If a memory mapped file +or a shared memory object +remains referenced at the last close (that is, a process has +it mapped), then the entire contents of the memory object shall +persist until the memory object becomes unreferenced. +If this is the last close of a memory mapped file +or a shared memory object +and the close results in the memory object becoming unreferenced, +and the memory object has been unlinked, then the memory object +shall be removed. +.P +If +.IR fildes +refers to a socket, +\fIclose\fR() +shall cause the socket to be destroyed. If the socket is in +connection-mode, and the SO_LINGER option is set for the socket with +non-zero linger time, and the socket has untransmitted data, then +\fIclose\fR() +shall block for up to the current linger interval until all data is +transmitted. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIclose\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a open file descriptor. +.TP +.BR EINTR +The +\fIclose\fR() +function was interrupted by a signal. +.P +The +\fIclose\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reassigning a File Descriptor" +.P +The following example closes the file descriptor associated with +standard output for the current process, re-assigns standard output to +a new file descriptor, and closes the original file descriptor to clean +up. This example assumes that the file descriptor 0 (which is the +descriptor for standard input) is not closed. +.sp +.RS 4 +.nf + +#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +.fi +.P +.RE +.P +Incidentally, this is exactly what could be achieved using: +.sp +.RS 4 +.nf + +dup2(pfd, 1); +close(pfd); +.fi +.P +.RE +.SS "Closing a File Descriptor" +.P +In the following example, +\fIclose\fR() +is used to close +a file descriptor after an unsuccessful attempt is made to associate that +file descriptor with a stream. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +FILE *fpfd; +\&... +if ((fpfd = fdopen (pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +An application that had used the +.IR stdio +routine +\fIfopen\fR() +to open a file should use the corresponding +\fIfclose\fR() +routine rather than +\fIclose\fR(). +Once a file is closed, the file descriptor no longer exists, since the +integer corresponding to it no longer refers to a file. +.P +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIclose\fR() +on an arbitrary integer risks non-conforming behavior, and +\fIclose\fR() +can only portably be used on file descriptor values that the application +has obtained through explicit actions, as well as the three file +descriptors corresponding to the standard file streams. In multi-threaded +parent applications, the practice of calling +\fIclose\fR() +in a loop after +\fIfork\fR() +and before an +.IR exec +call in order to avoid a race condition of leaking an unintended file +descriptor into a child process, is therefore unsafe, and the race should +instead be combatted by opening all file descriptors with the FD_CLOEXEC +bit set unless the file descriptor is intended to be inherited across +.IR exec . +.P +Usage of +\fIclose\fR() +on file descriptors STDIN_FILENO, STDOUT_FILENO, or STDERR_FILENO +should immediately be followed by an operation to reopen these file +descriptors. Unexpected behavior will result if any of these file +descriptors is left in a closed state (for example, an +.BR [EBADF] +error from +\fIperror\fR()) +or if an unrelated +\fIopen\fR() +or similar call later in the application accidentally allocates +a file to one of these well-known file descriptors. Furthermore, a +\fIclose\fR() +followed by a reopen operation (e.g., +\fIopen\fR(), +\fIdup\fR(), +etc.) is not atomic; +\fIdup2\fR() +should be used to change standard file descriptors. +.SH RATIONALE +The use of interruptible device close routines should be discouraged to +avoid problems with the implicit closes of file descriptors by +.IR exec +and +\fIexit\fR(). +This volume of POSIX.1\(hy2017 only intends to permit such behavior by specifying the +.BR [EINTR] +error condition. +.P +Note that the requirement for +\fIclose\fR() +on a socket to block for up to the current linger interval is not +conditional on the O_NONBLOCK setting. +.P +The standard developers rejected a proposal to add +\fIclosefrom\fR() +to the standard. Because the standard permits implementations to +use inherited file descriptors as a means of providing a conforming +environment for the child process, it is not possible to standardize an +interface that closes arbitrary file descriptors above a certain value +while still guaranteeing a conforming environment. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfattach\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/closedir.3p b/upstream/archlinux/man3p/closedir.3p new file mode 100644 index 00000000..3119103a --- /dev/null +++ b/upstream/archlinux/man3p/closedir.3p @@ -0,0 +1,110 @@ +'\" et +.TH CLOSEDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +closedir +\(em close a directory stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int closedir(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fIclosedir\fR() +function shall close the directory stream referred to by the argument +.IR dirp . +Upon return, the value of +.IR dirp +may no longer point to an accessible object of the type +.BR DIR . +If a file descriptor is used to implement type +.BR DIR , +that file descriptor shall be closed. +.SH "RETURN VALUE" +Upon successful completion, +\fIclosedir\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIclosedir\fR() +function may fail if: +.TP +.BR EBADF +The +.IR dirp +argument does not refer to an open directory stream. +.TP +.BR EINTR +The +\fIclosedir\fR() +function was interrupted by a signal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Closing a Directory Stream" +.P +The following program fragment demonstrates how the +\fIclosedir\fR() +function is used. +.sp +.RS 4 +.nf + +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { +\&... + } +.P + while ((dp = readdir (dir)) != NULL) { +\&... + } +.P + closedir(dir); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/closelog.3p b/upstream/archlinux/man3p/closelog.3p new file mode 100644 index 00000000..2b5a2af1 --- /dev/null +++ b/upstream/archlinux/man3p/closelog.3p @@ -0,0 +1,293 @@ +'\" et +.TH CLOSELOG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +closelog, +openlog, +setlogmask, +syslog +\(em control system log +.SH SYNOPSIS +.LP +.nf +#include +.P +void closelog(void); +void openlog(const char *\fIident\fP, int \fIlogopt\fP, int \fIfacility\fP); +int setlogmask(int \fImaskpri\fP); +void syslog(int \fIpriority\fP, const char *\fImessage\fP, ... /* \fIarguments\fP */); +.fi +.SH DESCRIPTION +The +\fIsyslog\fR() +function shall send a message to an implementation-defined logging +facility, which may log it in an implementation-defined system log, +write it to the system console, forward it to a list of users, or +forward it to the logging facility on another host over the network. +The logged message shall include a message header and a message body. +The message header contains at least a timestamp and a tag string. +.P +The message body is generated from the +.IR message +and following arguments in the same manner as if these were arguments +to +\fIprintf\fR(), +except that the additional conversion specification +.BR %m +shall be recognized; it shall convert no arguments, shall cause the +output of the error message string associated with the value of +.IR errno +on entry to +\fIsyslog\fR(), +and may be mixed with argument specifications of the \fR"%\fIn\fR$"\fR +form. If a complete conversion specification with the +.BR m +conversion specifier character is not just +.BR %m , +the behavior is undefined. A trailing + +may be added if needed. +.P +Values of the +.IR priority +argument are formed by OR'ing together a severity-level value and an +optional facility value. If no facility value is specified, the current +default facility value is used. +.P +Possible values of severity level include: +.IP LOG_EMERG 12 +A panic condition. +.IP LOG_ALERT 12 +A condition that should be corrected immediately, such as a corrupted +system database. +.IP LOG_CRIT 12 +Critical conditions, such as hard device errors. +.IP LOG_ERR 12 +Errors. +.IP LOG_WARNING 12 +.br +Warning messages. +.IP LOG_NOTICE 12 +Conditions that are not error conditions, but that may require special +handling. +.IP LOG_INFO 12 +Informational messages. +.IP LOG_DEBUG 12 +Messages that contain information normally of use only when debugging a +program. +.P +The facility indicates the application or system component generating +the message. Possible facility values include: +.IP LOG_USER 12 +Messages generated by arbitrary processes. This is the default facility +identifier if none is specified. +.IP LOG_LOCAL0 12 +Reserved for local use. +.IP LOG_LOCAL1 12 +Reserved for local use. +.IP LOG_LOCAL2 12 +Reserved for local use. +.IP LOG_LOCAL3 12 +Reserved for local use. +.IP LOG_LOCAL4 12 +Reserved for local use. +.IP LOG_LOCAL5 12 +Reserved for local use. +.IP LOG_LOCAL6 12 +Reserved for local use. +.IP LOG_LOCAL7 12 +Reserved for local use. +.P +The +\fIopenlog\fR() +function shall set process attributes that affect subsequent calls to +\fIsyslog\fR(). +The +.IR ident +argument is a string that is prepended to every message. The +.IR logopt +argument indicates logging options. Values for +.IR logopt +are constructed by a bitwise-inclusive OR of zero or more of the +following: +.IP LOG_PID 12 +Log the process ID with each message. This is useful for identifying +specific processes. +.IP LOG_CONS 12 +Write messages to the system console if they cannot be sent to the +logging facility. The +\fIsyslog\fR() +function ensures that the process does not acquire the console as a +controlling terminal in the process of writing the message. +.IP LOG_NDELAY 12 +Open the connection to the logging facility immediately. Normally the +open is delayed until the first message is logged. This is useful for +programs that need to manage the order in which file descriptors are +allocated. +.IP LOG_ODELAY 12 +Delay open until +\fIsyslog\fR() +is called. +.IP LOG_NOWAIT 12 +Do not wait for child processes that may have been created during the +course of logging the message. This option should be used by processes +that enable notification of child termination using SIGCHLD, since +\fIsyslog\fR() +may otherwise block waiting for a child whose exit status has already +been collected. +.P +The +.IR facility +argument encodes a default facility to be assigned to all messages that +do not have an explicit facility already encoded. The initial default +facility is LOG_USER. +.P +The +\fIopenlog\fR() +and +\fIsyslog\fR() +functions may allocate a file descriptor. It is not necessary to call +\fIopenlog\fR() +prior to calling +\fIsyslog\fR(). +.P +The +\fIcloselog\fR() +function shall close any open file descriptors allocated by previous +calls to +\fIopenlog\fR() +or +\fIsyslog\fR(). +.P +The +\fIsetlogmask\fR() +function shall set the log priority mask for the current process to +.IR maskpri +and return the previous mask. If the +.IR maskpri +argument is 0, the current log mask is not modified. Calls by the +current process to +\fIsyslog\fR() +with a priority not set in +.IR maskpri +shall be rejected. The default log mask allows all priorities to be +logged. A call to +\fIopenlog\fR() +is not required prior to calling +\fIsetlogmask\fR(). +.P +Symbolic constants for use as values of the +.IR logopt , +.IR facility , +.IR priority , +and +.IR maskpri +arguments are defined in the +.IR +header. +.SH "RETURN VALUE" +The +\fIsetlogmask\fR() +function shall return the previous log priority mask. The +\fIcloselog\fR(), +\fIopenlog\fR(), +and +\fIsyslog\fR() +functions shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using openlog(\|)" +.P +The following example causes subsequent calls to +\fIsyslog\fR() +to log the process ID with each message, and to write messages to the +system console if they cannot be sent to the logging facility. +.sp +.RS 4 +.nf + +#include +.P +char *ident = "Process demo"; +int logopt = LOG_PID | LOG_CONS; +int facility = LOG_USER; +\&... +openlog(ident, logopt, facility); +.fi +.P +.RE +.SS "Using setlogmask(\|)" +.P +The following example causes subsequent calls to +\fIsyslog\fR() +to accept error messages, and to reject all other messages. +.sp +.RS 4 +.nf + +#include +.P +int result; +int mask = LOG_MASK (LOG_ERR); +\&... +result = setlogmask(mask); +.fi +.P +.RE +.SS "Using syslog" +.P +The following example sends the message +.BR \(dqThis is a message\(dq +to the default logging facility, marking the message as an error +message generated by random processes. +.sp +.RS 4 +.nf + +#include +.P +char *message = "This is a message"; +int priority = LOG_ERR | LOG_USER; +\&... +syslog(priority, message); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/confstr.3p b/upstream/archlinux/man3p/confstr.3p new file mode 100644 index 00000000..2ec41bde --- /dev/null +++ b/upstream/archlinux/man3p/confstr.3p @@ -0,0 +1,283 @@ +'\" et +.TH CONFSTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +confstr +\(em get configurable variables +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t confstr(int \fIname\fP, char *\fIbuf\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fIconfstr\fR() +function shall return configuration-defined string values. Its use and +purpose are similar to +\fIsysconf\fR(), +but it is used where string values rather than numeric values are +returned. +.P +The +.IR name +argument represents the system variable to be queried. The +implementation shall support the following name values, defined in +.IR . +It may support others: +.P +.nf +_CS_PATH +_CS_POSIX_V7_ILP32_OFF32_CFLAGS +_CS_POSIX_V7_ILP32_OFF32_LDFLAGS +_CS_POSIX_V7_ILP32_OFF32_LIBS +_CS_POSIX_V7_ILP32_OFFBIG_CFLAGS +_CS_POSIX_V7_ILP32_OFFBIG_LDFLAGS +_CS_POSIX_V7_ILP32_OFFBIG_LIBS +_CS_POSIX_V7_LP64_OFF64_CFLAGS +_CS_POSIX_V7_LP64_OFF64_LDFLAGS +_CS_POSIX_V7_LP64_OFF64_LIBS +_CS_POSIX_V7_LPBIG_OFFBIG_CFLAGS +_CS_POSIX_V7_LPBIG_OFFBIG_LDFLAGS +_CS_POSIX_V7_LPBIG_OFFBIG_LIBS +_CS_POSIX_V7_THREADS_CFLAGS +_CS_POSIX_V7_THREADS_LDFLAGS +_CS_POSIX_V7_WIDTH_RESTRICTED_ENVS +_CS_V7_ENV +_CS_POSIX_V6_ILP32_OFF32_CFLAGS +_CS_POSIX_V6_ILP32_OFF32_LDFLAGS +_CS_POSIX_V6_ILP32_OFF32_LIBS +_CS_POSIX_V6_ILP32_OFFBIG_CFLAGS +_CS_POSIX_V6_ILP32_OFFBIG_LDFLAGS +_CS_POSIX_V6_ILP32_OFFBIG_LIBS +_CS_POSIX_V6_LP64_OFF64_CFLAGS +_CS_POSIX_V6_LP64_OFF64_LDFLAGS +_CS_POSIX_V6_LP64_OFF64_LIBS +_CS_POSIX_V6_LPBIG_OFFBIG_CFLAGS +_CS_POSIX_V6_LPBIG_OFFBIG_LDFLAGS +_CS_POSIX_V6_LPBIG_OFFBIG_LIBS +_CS_POSIX_V6_WIDTH_RESTRICTED_ENVS +_CS_V6_ENV +.fi +.P +If +.IR len +is not 0, and if +.IR name +has a configuration-defined value, +\fIconfstr\fR() +shall copy that value into the +.IR len -byte +buffer pointed to by +.IR buf . +If the string to be returned is longer than +.IR len +bytes, including the terminating null, then +\fIconfstr\fR() +shall truncate the string to +.IR len \-1 +bytes and null-terminate the result. The application can detect that +the string was truncated by comparing the value returned by +\fIconfstr\fR() +with +.IR len . +.P +If +.IR len +is 0 and +.IR buf +is a null pointer, then +\fIconfstr\fR() +shall still return the integer value as defined below, but shall not +return a string. If +.IR len +is 0 but +.IR buf +is not a null pointer, the result is unspecified. +.P +After a call to: +.sp +.RS 4 +.nf + +confstr(_CS_V7_ENV, buf, sizeof(buf)) +.fi +.P +.RE +.P +the string stored in +.IR buf +shall contain a +-separated +list of the variable=value environment variable pairs an +implementation requires as part of specifying a conforming +environment, as described in the implementations' conformance +documentation. +.P +If the implementation supports the POSIX shell option, the string +stored in +.IR buf +after a call to: +.sp +.RS 4 +.nf + +confstr(_CS_PATH, buf, sizeof(buf)) +.fi +.P +.RE +.P +can be used as a value of the +.IR PATH +environment variable that accesses all of the standard utilities of +POSIX.1\(hy2008, that are provided in a manner accessible via the +.IR exec +family of functions, if the return value is less than or equal to +.IR sizeof (\c +.IR buf ). +.SH "RETURN VALUE" +If +.IR name +has a configuration-defined value, +\fIconfstr\fR() +shall return the size of buffer that would be needed to hold the entire +configuration-defined value including the terminating null. If this +return value is greater than +.IR len , +the string returned in +.IR buf +is truncated. +.P +If +.IR name +is invalid, +\fIconfstr\fR() +shall return 0 and set +.IR errno +to indicate the error. +.P +If +.IR name +does not have a configuration-defined value, +\fIconfstr\fR() +shall return 0 and leave +.IR errno +unchanged. +.SH ERRORS +The +\fIconfstr\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR name +argument is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +An application can distinguish between an invalid +.IR name +parameter value and one that corresponds to a configurable variable +that has no configuration-defined value by checking if +.IR errno +is modified. This mirrors the behavior of +\fIsysconf\fR(). +.P +The original need for this function was to provide a way of finding the +configuration-defined default value for the environment variable +.IR PATH . +Since +.IR PATH +can be modified by the user to include directories that could contain +utilities replacing the standard utilities in the Shell and Utilities volume of POSIX.1\(hy2017, applications +need a way to determine the system-supplied +.IR PATH +environment variable value that contains the correct search path for +the standard utilities. +.P +An application could use: +.sp +.RS 4 +.nf + +confstr(name, (char *)NULL, (size_t)0) +.fi +.P +.RE +.P +to find out how big a buffer is needed for the string value; use +\fImalloc\fR() +to allocate a buffer to hold the string; and call +\fIconfstr\fR() +again to get the string. Alternately, it could allocate a fixed, static +buffer that is big enough to hold most answers (perhaps 512 or 1\|024 +bytes), but then use +\fImalloc\fR() +to allocate a larger buffer if it finds that this is too small. +.SH RATIONALE +Application developers can normally determine any configuration +variable by means of reading from the stream opened by a call to: +.sp +.RS 4 +.nf + +popen("command -p getconf variable", "r"); +.fi +.P +.RE +.P +The +\fIconfstr\fR() +function with a +.IR name +argument of _CS_PATH returns a string that can be used as a +.IR PATH +environment variable setting that will reference the standard shell and +utilities as described in the Shell and Utilities volume of POSIX.1\(hy2017. +.P +The +\fIconfstr\fR() +function copies the returned string into a buffer supplied by the +application instead of returning a pointer to a string. This allows a +cleaner function in some implementations (such as those with +lightweight threads) and resolves questions about when the application +must copy the string returned. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIc99\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/conj.3p b/upstream/archlinux/man3p/conj.3p new file mode 100644 index 00000000..d4850fef --- /dev/null +++ b/upstream/archlinux/man3p/conj.3p @@ -0,0 +1,71 @@ +'\" et +.TH CONJ "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +conj, +conjf, +conjl +\(em complex conjugate functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex conj(double complex \fIz\fP); +float complex conjf(float complex \fIz\fP); +long double complex conjl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex conjugate of +.IR z , +by reversing the sign of its imaginary part. +.SH "RETURN VALUE" +These functions return the complex conjugate value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/connect.3p b/upstream/archlinux/man3p/connect.3p new file mode 100644 index 00000000..bd2232c2 --- /dev/null +++ b/upstream/archlinux/man3p/connect.3p @@ -0,0 +1,303 @@ +'\" et +.TH CONNECT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +connect +\(em connect a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int connect(int \fIsocket\fP, const struct sockaddr *\fIaddress\fP, + socklen_t \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIconnect\fR() +function shall attempt to make a connection on a connection-mode +socket or to set or reset the peer address of a connectionless-mode +socket. The function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the file descriptor associated with the socket. +.IP "\fIaddress\fR" 12 +Points to a +.BR sockaddr +structure containing the peer address. The length and format of the +address depend on the address family of the socket. +.IP "\fIaddress_len\fR" 12 +Specifies the length of the +.BR sockaddr +structure pointed to by the +.IR address +argument. +.P +If the socket has not already been bound to a local address, +\fIconnect\fR() +shall bind it to an address which, unless the socket's address family +is AF_UNIX, is an unused local address. +.P +If the initiating socket is not connection-mode, then +\fIconnect\fR() +shall set the socket's peer address, and no connection is made. For +SOCK_DGRAM sockets, the peer address identifies where all datagrams are +sent on subsequent +\fIsend\fR() +functions, and limits the remote sender for subsequent +\fIrecv\fR() +functions. If the +.IR sa_family +member of +.IR address +is AF_UNSPEC, the socket's peer address shall be reset. Note that despite +no connection being made, the term ``connected'' is used to describe a +connectionless-mode socket for which a peer address has been set. +.P +If the initiating socket is connection-mode, then +\fIconnect\fR() +shall attempt to establish a connection to the address specified by the +.IR address +argument. If the connection cannot be established immediately and +O_NONBLOCK is not set for the file descriptor for the socket, +\fIconnect\fR() +shall block for up to an unspecified timeout interval until the +connection is established. If the timeout interval expires before the +connection is established, +\fIconnect\fR() +shall fail and the connection attempt shall be aborted. If +\fIconnect\fR() +is interrupted by a signal that is caught while blocked waiting to +establish a connection, +\fIconnect\fR() +shall fail and set +.IR errno +to +.BR [EINTR] , +but the connection request shall not be aborted, and the connection +shall be established asynchronously. +.P +If the connection cannot be established immediately and O_NONBLOCK is +set for the file descriptor for the socket, +\fIconnect\fR() +shall fail and set +.IR errno +to +.BR [EINPROGRESS] , +but the connection request shall not be aborted, and the connection +shall be established asynchronously. Subsequent calls to +\fIconnect\fR() +for the same socket, before the connection is established, shall fail +and set +.IR errno +to +.BR [EALREADY] . +.P +When the connection has been established asynchronously, +\fIpselect\fR(), +\fIselect\fR(), +and +\fIpoll\fR() +shall indicate that the file descriptor for the socket is ready for +writing. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIconnect\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIconnect\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIconnect\fR() +function shall fail if: +.TP +.BR EADDRNOTAVAIL +.br +The specified address is not available from the local machine. +.TP +.BR EAFNOSUPPORT +.br +The specified address is not a valid address for the address family of +the specified socket. +.TP +.BR EALREADY +A connection request is already in progress for the specified socket. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNREFUSED +.br +The target address was not listening for connections or refused the +connection request. +.TP +.BR EINPROGRESS +O_NONBLOCK is set for the file descriptor for the socket and the +connection cannot be immediately established; the connection shall be +established asynchronously. +.TP +.BR EINTR +The attempt to establish a connection was interrupted by delivery of a +signal that was caught; the connection shall be established +asynchronously. +.TP +.BR EISCONN +The specified socket is connection-mode and is already connected. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EPROTOTYPE +The specified address has a different type than the socket bound to the +specified peer address. +.TP +.BR ETIMEDOUT +The attempt to connect timed out before a connection was made. +.P +If the address family of the socket is AF_UNIX, then +\fIconnect\fR() +shall fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in +.IR address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in +.IR address +contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.P +The +\fIconnect\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP +.BR EADDRINUSE +Attempt to establish a connection that uses addresses that are already +in use. +.TP +.BR ECONNRESET +Remote host reset the connection request. +.TP +.BR EHOSTUNREACH +.br +The destination host cannot be reached (probably because the host is +down or a remote router cannot reach it). +.TP +.BR EINVAL +The +.IR address_len +argument is not a valid length for the address family; or invalid +address family in the +.BR sockaddr +structure. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +.IR address . +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENOBUFS +No buffer space is available. +.TP +.BR EOPNOTSUPP +The socket is listening and cannot be connected. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If +\fIconnect\fR() +fails, the state of the socket is unspecified. Conforming applications +should close the file descriptor and create a new socket before +attempting to reconnect. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/copysign.3p b/upstream/archlinux/man3p/copysign.3p new file mode 100644 index 00000000..676cb8ab --- /dev/null +++ b/upstream/archlinux/man3p/copysign.3p @@ -0,0 +1,76 @@ +'\" et +.TH COPYSIGN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +copysign, +copysignf, +copysignl +\(em number manipulation function +.SH SYNOPSIS +.LP +.nf +#include +.P +double copysign(double \fIx\fP, double \fIy\fP); +float copysignf(float \fIx\fP, float \fIy\fP); +long double copysignl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall produce a value with the magnitude of +.IR x +and the sign of +.IR y . +On implementations that represent a signed zero but do not treat +negative zero consistently in arithmetic operations, these functions +regard the sign of zero as positive. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value with +the magnitude of +.IR x +and the sign of +.IR y . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cos.3p b/upstream/archlinux/man3p/cos.3p new file mode 100644 index 00000000..a13b0b21 --- /dev/null +++ b/upstream/archlinux/man3p/cos.3p @@ -0,0 +1,128 @@ +'\" et +.TH COS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cos, +cosf, +cosl +\(em cosine function +.SH SYNOPSIS +.LP +.nf +#include +.P +double cos(double \fIx\fP); +float cosf(float \fIx\fP); +long double cosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the cosine of their argument +.IR x , +measured in radians. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the cosine of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, the value 1.0 shall be returned. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Cosine of a 45-Degree Angle" +.sp +.RS 4 +.nf + +#include +\&... +double radians = 45 * M_PI / 180; +double result; +\&... +result = cos(radians); +.fi +.P +.RE +.SH "APPLICATION USAGE" +These functions may lose accuracy when their argument is near an odd +multiple of \(*p/2 or is far from 0. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIacos\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsin\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cosh.3p b/upstream/archlinux/man3p/cosh.3p new file mode 100644 index 00000000..4ea70591 --- /dev/null +++ b/upstream/archlinux/man3p/cosh.3p @@ -0,0 +1,119 @@ +'\" et +.TH COSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cosh, +coshf, +coshl +\(em hyperbolic cosine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double cosh(double \fIx\fP); +float coshf(float \fIx\fP); +long double coshl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the hyperbolic cosine of their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the hyperbolic +cosine of +.IR x . +.P +If the correct value would cause overflow, a range error shall occur +and +\fIcosh\fR(), +\fIcoshf\fR(), +and +\fIcoshl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, the value 1.0 shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result would cause an overflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIacosh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsinh\fR\^(\|)", +.IR "\fItanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cosl.3p b/upstream/archlinux/man3p/cosl.3p new file mode 100644 index 00000000..adb42ac4 --- /dev/null +++ b/upstream/archlinux/man3p/cosl.3p @@ -0,0 +1,40 @@ +'\" et +.TH COSL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cosl +\(em cosine function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double cosl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcos\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cpow.3p b/upstream/archlinux/man3p/cpow.3p new file mode 100644 index 00000000..bb53e62b --- /dev/null +++ b/upstream/archlinux/man3p/cpow.3p @@ -0,0 +1,70 @@ +'\" et +.TH CPOW "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cpow, +cpowf, +cpowl +\(em complex power functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cpow(double complex \fIx\fP, double complex \fIy\fP); +float complex cpowf(float complex \fIx\fP, float complex \fIy\fP); +long double complex cpowl(long double complex \fIx\fP, + long double complex \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex power function +\fIx\s-3\uy\d\s+3\fR, with a branch cut for the first parameter along +the negative real axis. +.SH "RETURN VALUE" +These functions shall return the complex power function value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcabs\fR\^(\|)", +.IR "\fIcsqrt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/cproj.3p b/upstream/archlinux/man3p/cproj.3p new file mode 100644 index 00000000..53b31d09 --- /dev/null +++ b/upstream/archlinux/man3p/cproj.3p @@ -0,0 +1,106 @@ +'\" et +.TH CPROJ "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +cproj, +cprojf, +cprojl +\(em complex projection functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex cproj(double complex \fIz\fP); +float complex cprojf(float complex \fIz\fP); +long double complex cprojl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute a projection of +.IR z +onto the Riemann sphere: +.IR z +projects to +.IR z , +except that all complex infinities (even those with one infinite part +and one NaN part) project to positive infinity on the real axis. If +.IR z +has an infinite part, then +.IR cproj (\c +.IR z ) +shall be equivalent to: +.sp +.RS 4 +.nf + +INFINITY + I * copysign(0.0, cimag(z)) +.fi +.P +.RE +.SH "RETURN VALUE" +These functions shall return the value of the projection onto the +Riemann sphere. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Two topologies are commonly used in complex mathematics: the complex +plane with its continuum of infinities, and the Riemann sphere with its +single infinity. The complex plane is better suited for transcendental +functions, the Riemann sphere for algebraic functions. The complex +types with their multiplicity of infinities provide a useful (though +imperfect) model for the complex plane. The +\fIcproj\fR() +function helps model the Riemann sphere by mapping all infinities to +one, and should be used just before any operation, especially +comparisons, that might give spurious results for any of the other +infinities. Note that a complex value with one infinite part and one +NaN part is regarded as an infinity, not a NaN, because if one part is +infinite, the complex value is infinite independent of the value of the +other part. For the same reason, +\fIcabs\fR() +returns an infinity if its argument has an infinite part and a NaN +part. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcreal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/creal.3p b/upstream/archlinux/man3p/creal.3p new file mode 100644 index 00000000..101271b4 --- /dev/null +++ b/upstream/archlinux/man3p/creal.3p @@ -0,0 +1,81 @@ +'\" et +.TH CREAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +creal, +crealf, +creall +\(em complex real functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double creal(double complex \fIz\fP); +float crealf(float complex \fIz\fP); +long double creall(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the real part of +.IR z . +.SH "RETURN VALUE" +These functions shall return the real part value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For a variable +.IR z +of type +.BR complex : +.sp +.RS 4 +.nf + +z == creal(z) + cimag(z)*I +.fi +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcarg\fR\^(\|)", +.IR "\fIcimag\fR\^(\|)", +.IR "\fIconj\fR\^(\|)", +.IR "\fIcproj\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/creat.3p b/upstream/archlinux/man3p/creat.3p new file mode 100644 index 00000000..8ccc64ab --- /dev/null +++ b/upstream/archlinux/man3p/creat.3p @@ -0,0 +1,106 @@ +'\" et +.TH CREAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +creat +\(em create a new file or rewrite an existing one +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int creat(const char *\fIpath\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIcreat\fR() +function shall behave as if it is implemented as follows: +.sp +.RS 4 +.nf + +int creat(const char *path, mode_t mode) +{ + return open(path, O_WRONLY|O_CREAT|O_TRUNC, mode); +} +.fi +.P +.RE +.SH "RETURN VALUE" +Refer to +.IR "\fIopen\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIopen\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a File" +.P +The following example creates the file +.BR /tmp/file +with read and write permissions for the file owner and read permission +for group and others. The resulting file descriptor is assigned to the +.IR fd +variable. +.sp +.RS 4 +.nf + +#include +\&... +int fd; +mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; +char *pathname = "/tmp/file"; +\&... +fd = creat(pathname, mode); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIcreat\fR() +function is redundant. Its services are also provided by the +\fIopen\fR() +function. It has been included primarily for historical purposes since +many existing applications depend on it. It is best considered a part +of the C binding rather than a function that should be provided in +other languages. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/crypt.3p b/upstream/archlinux/man3p/crypt.3p new file mode 100644 index 00000000..1a73079b --- /dev/null +++ b/upstream/archlinux/man3p/crypt.3p @@ -0,0 +1,165 @@ +'\" et +.TH CRYPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +crypt +\(em string encoding function +(\fBCRYPT\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +char *crypt(const char *\fIkey\fP, const char *\fIsalt\fP); +.fi +.SH DESCRIPTION +The +\fIcrypt\fR() +function is a string encoding function. The algorithm is +implementation-defined. +.P +The +.IR key +argument points to a string to be encoded. The +.IR salt +argument shall be a string of at least two bytes in length not +including the null character chosen from the set: +.sp +.RS 4 +.nf + +a b c d e f g h i j k l m n o p q r s t u v w x y z +A B C D E F G H I J K L M N O P Q R S T U V W X Y Z +0 1 2 3 4 5 6 7 8 9 . / +.fi +.P +.RE +.P +The first two bytes of this string may be used to perturb the +encoding algorithm. +.P +The return value of +\fIcrypt\fR() +points to static data that is overwritten by each call. +.P +The +\fIcrypt\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIcrypt\fR() +shall return a pointer to the encoded string. The first two bytes +of the returned value shall be those of the +.IR salt +argument. Otherwise, it shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIcrypt\fR() +function shall fail if: +.TP +.BR ENOSYS +The functionality is not supported on this implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Encoding Passwords" +.P +The following example finds a user database entry matching a particular +user name and changes the current password to a new password. The +\fIcrypt\fR() +function generates an encoded version of each password. The +first call to +\fIcrypt\fR() +produces an encoded version of the old password; that encoded password +is then compared to the password stored in the user database. The +second call to +\fIcrypt\fR() +encodes the new password before it is stored. +.P +The +\fIputpwent\fR() +function, used in the following example, is not part of POSIX.1\(hy2008. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +\&... +int valid_change; +int pfd; /* Integer for file descriptor returned by open(). */ +FILE *fpfd; /* File pointer for use in putpwent(). */ +struct passwd *p; +char user[100]; +char oldpasswd[100]; +char newpasswd[100]; +char savepasswd[100]; +\&... +valid_change = 0; +while ((p = getpwent()) != NULL) { + /* Change entry if found. */ + if (strcmp(p->pw_name, user) == 0) { + if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { + strcpy(savepasswd, crypt(newpasswd, user)); + p->pw_passwd = savepasswd; + valid_change = 1; + } + else { + fprintf(stderr, "Old password is not valid\en"); + } + } + /* Put passwd entry into ptmp. */ + putpwent(p, fpfd); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The values returned by this function need not be portable among +XSI-conformant systems. +.P +Several implementations offer extensions via characters outside +of the set specified for the +.IR salt +argument for specifying alternative algorithms; while not portable, these +extensions may offer better security. The use of +\fIcrypt\fR() +for anything other than password hashing is not recommended. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIencrypt\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/csin.3p b/upstream/archlinux/man3p/csin.3p new file mode 100644 index 00000000..fab71998 --- /dev/null +++ b/upstream/archlinux/man3p/csin.3p @@ -0,0 +1,67 @@ +'\" et +.TH CSIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +csin, +csinf, +csinl +\(em complex sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex csin(double complex \fIz\fP); +float complex csinf(float complex \fIz\fP); +long double complex csinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex sine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex sine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcasin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/csinh.3p b/upstream/archlinux/man3p/csinh.3p new file mode 100644 index 00000000..b11e78da --- /dev/null +++ b/upstream/archlinux/man3p/csinh.3p @@ -0,0 +1,67 @@ +'\" et +.TH CSINH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +csinh, +csinhf, +csinhl +\(em complex hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex csinh(double complex \fIz\fP); +float complex csinhf(float complex \fIz\fP); +long double complex csinhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex hyperbolic sine of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex hyperbolic sine value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcasinh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/csinl.3p b/upstream/archlinux/man3p/csinl.3p new file mode 100644 index 00000000..ce17c26d --- /dev/null +++ b/upstream/archlinux/man3p/csinl.3p @@ -0,0 +1,40 @@ +'\" et +.TH CSINL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +csinl +\(em complex sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex csinl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcsin\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/csqrt.3p b/upstream/archlinux/man3p/csqrt.3p new file mode 100644 index 00000000..1ef26ac6 --- /dev/null +++ b/upstream/archlinux/man3p/csqrt.3p @@ -0,0 +1,70 @@ +'\" et +.TH CSQRT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +csqrt, +csqrtf, +csqrtl +\(em complex square root functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex csqrt(double complex \fIz\fP); +float complex csqrtf(float complex \fIz\fP); +long double complex csqrtl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex square root of +.IR z , +with a branch cut along the negative real axis. +.SH "RETURN VALUE" +These functions shall return the complex square root value, in the +range of the right half-plane (including the imaginary axis). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcabs\fR\^(\|)", +.IR "\fIcpow\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ctan.3p b/upstream/archlinux/man3p/ctan.3p new file mode 100644 index 00000000..588dfa56 --- /dev/null +++ b/upstream/archlinux/man3p/ctan.3p @@ -0,0 +1,67 @@ +'\" et +.TH CTAN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ctan, +ctanf, +ctanl +\(em complex tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ctan(double complex \fIz\fP); +float complex ctanf(float complex \fIz\fP); +long double complex ctanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex tangent of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex tangent value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ctanh.3p b/upstream/archlinux/man3p/ctanh.3p new file mode 100644 index 00000000..019513ff --- /dev/null +++ b/upstream/archlinux/man3p/ctanh.3p @@ -0,0 +1,67 @@ +'\" et +.TH CTANH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ctanh, +ctanhf, +ctanhl +\(em complex hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double complex ctanh(double complex \fIz\fP); +float complex ctanhf(float complex \fIz\fP); +long double complex ctanhl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complex hyperbolic tangent of +.IR z . +.SH "RETURN VALUE" +These functions shall return the complex hyperbolic tangent value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcatanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ctanl.3p b/upstream/archlinux/man3p/ctanl.3p new file mode 100644 index 00000000..0694e8c5 --- /dev/null +++ b/upstream/archlinux/man3p/ctanl.3p @@ -0,0 +1,40 @@ +'\" et +.TH CTANL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ctanl +\(em complex tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +long double complex ctanl(long double complex \fIz\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIctan\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ctermid.3p b/upstream/archlinux/man3p/ctermid.3p new file mode 100644 index 00000000..503f0505 --- /dev/null +++ b/upstream/archlinux/man3p/ctermid.3p @@ -0,0 +1,148 @@ +'\" et +.TH CTERMID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ctermid +\(em generate a pathname for the controlling terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ctermid(char *\fIs\fP); +.fi +.SH DESCRIPTION +The +\fIctermid\fR() +function shall generate a string that, when used as a pathname, +refers to the current controlling terminal for the current process. If +\fIctermid\fR() +returns a pathname, access to the file is not guaranteed. +.P +The +\fIctermid\fR() +function need not be thread-safe if called with a NULL parameter. +.SH "RETURN VALUE" +If +.IR s +is a null pointer, the string shall be generated in an area that may be +static, the address of which shall be returned. The application shall +not modify the string returned. The returned pointer might be invalidated +or the string content might be overwritten by a subsequent call to +\fIctermid\fR(). +The returned pointer might also be invalidated if the calling thread +is terminated. +If +.IR s +is not a null pointer, +.IR s +is assumed to point to a character array of at least L_ctermid bytes; +the string is placed in this array and the value of +.IR s +shall be returned. The symbolic constant L_ctermid is defined in +.IR , +and shall have a value greater than 0. +.P +The +\fIctermid\fR() +function shall return an empty string if the pathname that would refer +to the controlling terminal cannot be determined, or if the function is +unsuccessful. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Determining the Controlling Terminal for the Current Process" +.P +The following example returns a pointer to a string that identifies the +controlling terminal for the current process. The pathname for the +terminal is stored in the array pointed to by the +.IR ptr +argument, which has a size of L_ctermid bytes, as indicated by the +.IR term +argument. +.sp +.RS 4 +.nf + +#include +\&... +char term[L_ctermid]; +char *ptr; +.P +ptr = ctermid(term); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The difference between +\fIctermid\fR() +and +\fIttyname\fR() +is that +\fIttyname\fR() +must be handed a file descriptor and return a path of the terminal +associated with that file descriptor, while +\fIctermid\fR() +returns a string (such as +.BR \(dq/dev/tty\(dq ) +that refers to the current controlling terminal if used as a +pathname. +.SH RATIONALE +L_ctermid +must be defined appropriately for a given implementation and must be +greater than zero so that array declarations using it are accepted by +the compiler. The value includes the terminating null byte. +.P +Conforming applications that use multiple threads cannot call +\fIctermid\fR() +with NULL as the parameter. If +.IR s +is not NULL, the +\fIctermid\fR() +function generates a string that, when used as a pathname, refers to +the current controlling terminal for the current process. If +.IR s +is NULL, the return value of +\fIctermid\fR() +is undefined. +.P +There is no additional burden on the programmer\(emchanging to use a +hypothetical thread-safe version of +\fIctermid\fR() +along with allocating a buffer is more of a burden than merely +allocating a buffer. Application code should not assume that the +returned string is short, as some implementations have more than two +pathname components before reaching a logical device name. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIttyname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ctime.3p b/upstream/archlinux/man3p/ctime.3p new file mode 100644 index 00000000..310b1db2 --- /dev/null +++ b/upstream/archlinux/man3p/ctime.3p @@ -0,0 +1,183 @@ +'\" et +.TH CTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ctime, +ctime_r +\(em convert a time value to a date and time string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ctime(const time_t *\fIclock\fP); +char *ctime_r(const time_t *\fIclock\fP, char *\fIbuf\fP); +.fi +.SH DESCRIPTION +For +\fIctime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIctime\fR() +function shall convert the time pointed to by +.IR clock , +representing time in seconds since the Epoch, to local time in the form +of a string. It shall be equivalent to: +.sp +.RS 4 +.nf + +asctime(localtime(clock)) +.fi +.P +.RE +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIctime\fR() +function need not be thread-safe. +.P +The +\fIctime_r\fR() +function shall convert the calendar time pointed to by +.IR clock +to local time in exactly the same form as +\fIctime\fR() +and put the string into the array pointed to by +.IR buf +(which shall be at least 26 bytes in size) and return +.IR buf . +.P +Unlike +\fIctime\fR(), +the +\fIctime_r\fR() +function is not required to set +.IR tzname . +If +\fIctime_r\fR() +sets +.IR tzname , +it shall also set +.IR daylight +and +.IR timezone . +If +\fIctime_r\fR() +does not set +.IR tzname , +it shall not set +.IR daylight +and shall not set +.IR timezone . +.SH "RETURN VALUE" +The +\fIctime\fR() +function shall return the pointer returned by +\fIasctime\fR() +with that broken-down time as an argument. +.P +Upon successful completion, +\fIctime_r\fR() +shall return a pointer to the string pointed to by +.IR buf . +When an error is encountered, a null pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are included only for compatibility with older +implementations. They have undefined behavior if the resulting string +would be too long, so the use of these functions should be discouraged. +On implementations that do not detect output string length overflow, it +is possible to overflow the output buffers in such a way as to cause +applications to fail, or possible system security violations. Also, +these functions do not support localized date and time formats. To +avoid these problems, applications should use +\fIstrftime\fR() +to generate strings from broken-down times. +.P +Values for the broken-down time structure can be obtained by calling +\fIgmtime\fR() +or +\fIlocaltime\fR(). +.P +The +\fIctime_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.P +Attempts to use +\fIctime\fR() +or +\fIctime_r\fR() +for times before the Epoch or for times beyond the year 9999 produce +undefined results. Refer to +.IR "\fIasctime\fR\^(\|)". +.SH RATIONALE +The standard developers decided to mark the +\fIctime\fR() +and +\fIctime_r\fR() +functions obsolescent even though they are in the ISO\ C standard due to the +possibility of buffer overflow. The ISO\ C standard also provides the +\fIstrftime\fR() +function which can be used to avoid these problems. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/daylight.3p b/upstream/archlinux/man3p/daylight.3p new file mode 100644 index 00000000..6bef562e --- /dev/null +++ b/upstream/archlinux/man3p/daylight.3p @@ -0,0 +1,40 @@ +'\" et +.TH DAYLIGHT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +daylight +\(em daylight savings time flag +.SH SYNOPSIS +.LP +.nf +#include +.P +extern int daylight; +.fi +.SH DESCRIPTION +Refer to +.IR "\fItzset\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dbm_clearerr.3p b/upstream/archlinux/man3p/dbm_clearerr.3p new file mode 100644 index 00000000..639d03c3 --- /dev/null +++ b/upstream/archlinux/man3p/dbm_clearerr.3p @@ -0,0 +1,405 @@ +'\" et +.TH DBM_CLEARERR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dbm_clearerr, +dbm_close, +dbm_delete, +dbm_error, +dbm_fetch, +dbm_firstkey, +dbm_nextkey, +dbm_open, +dbm_store +\(em database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int dbm_clearerr(DBM *\fIdb\fP); +void dbm_close(DBM *\fIdb\fP); +int dbm_delete(DBM *\fIdb\fP, datum \fIkey\fP); +int dbm_error(DBM *\fIdb\fP); +datum dbm_fetch(DBM *\fIdb\fP, datum \fIkey\fP); +datum dbm_firstkey(DBM *\fIdb\fP); +datum dbm_nextkey(DBM *\fIdb\fP); +DBM *dbm_open(const char *\fIfile\fP, int \fIopen_flags\fP, mode_t \fIfile_mode\fP); +int dbm_store(DBM *\fIdb\fP, datum \fIkey\fP, datum \fIcontent\fP, int \fIstore_mode\fP); +.fi +.SH DESCRIPTION +These functions create, access, and modify a database. +.P +A +.BR datum +consists of at least two members, +.IR dptr +and +.IR dsize . +The +.IR dptr +member points to an object that is +.IR dsize +bytes in length. Arbitrary binary data, as well as character strings, +may be stored in the object pointed to by +.IR dptr . +.P +A database shall be stored in one or two files. When one file is used, +the name of the database file shall be formed by appending the suffix +.BR .db +to the +.IR file +argument given to +\fIdbm_open\fR(). +When two files are used, the names of the database files shall be +formed by appending the suffixes +.BR .dir +and +.BR .pag +respectively to the +.IR file +argument. +.P +The +\fIdbm_open\fR() +function shall open a database. The +.IR file +argument to the function is the pathname of the database. The +.IR open_flags +argument has the same meaning as the +.IR flags +argument of +\fIopen\fR() +except that a database opened for write-only access opens the files for +read and write access and the behavior of the O_APPEND flag +is unspecified. The +.IR file_mode +argument has the same meaning as the third argument of +\fIopen\fR(). +.P +The +\fIdbm_open\fR() +function need not accept pathnames longer than +{PATH_MAX}\-4 +bytes (including the terminating null), or pathnames with a last +component longer than +{NAME_MAX}\-4 +bytes (excluding the terminating null). +.P +The +\fIdbm_close\fR() +function shall close a database. The application shall ensure that +argument +.IR db +is a pointer to a +.BR dbm +structure that has been returned from a call to +\fIdbm_open\fR(). +.P +These database functions shall support an internal block size large +enough to support key/content pairs of at least 1\|023 bytes. +.P +The +\fIdbm_fetch\fR() +function shall read a record from a database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The argument +.IR key +is a +.BR datum +that has been initialized by the application to the value of +the key that matches the key of the record the program is fetching. +.P +The +\fIdbm_store\fR() +function shall write a record to a database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The argument +.IR key +is a +.BR datum +that has been initialized by the application to the value of the key +that identifies (for subsequent reading, writing, or deleting) the +record the application is writing. The argument +.IR content +is a +.BR datum +that has been initialized by the application to the value of the record +the program is writing. The argument +.IR store_mode +controls whether +\fIdbm_store\fR() +replaces any pre-existing record that has the same key that is +specified by the +.IR key +argument. The application shall set +.IR store_mode +to either DBM_INSERT or DBM_REPLACE. If the database contains a record +that matches the +.IR key +argument and +.IR store_mode +is DBM_REPLACE, the existing record shall be replaced with the new +record. If the database contains a record that matches the +.IR key +argument and +.IR store_mode +is DBM_INSERT, the existing record shall be left unchanged and the new +record ignored. If the database does not contain a record that matches +the +.IR key +argument and +.IR store_mode +is either DBM_INSERT or DBM_REPLACE, the new record shall be inserted +in the database. +.P +If the sum of a key/content pair exceeds the internal block size, the +result is unspecified. Moreover, the application shall ensure that all +key/content pairs that hash together fit on a single block. The +\fIdbm_store\fR() +function shall return an error in the event that a disk block fills +with inseparable data. +.P +The +\fIdbm_delete\fR() +function shall delete a record and its key from the database. The +argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The argument +.IR key +is a +.BR datum +that has been initialized by the application to the value of +the key that identifies the record the program is deleting. +.P +The +\fIdbm_firstkey\fR() +function shall return the first key in the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +.P +The +\fIdbm_nextkey\fR() +function shall return the next key in the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +The application shall ensure that the +\fIdbm_firstkey\fR() +function is called before calling +\fIdbm_nextkey\fR(). +Subsequent calls to +\fIdbm_nextkey\fR() +return the next key until all of the keys in the database have been +returned. +.P +The +\fIdbm_error\fR() +function shall return the error condition of the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +.P +The +\fIdbm_clearerr\fR() +function shall clear the error condition of the database. The argument +.IR db +is a pointer to a database structure that has been returned from a call +to +\fIdbm_open\fR(). +.P +The +.IR dptr +pointers returned by these functions may point into static storage that +may be changed by subsequent calls. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +The +\fIdbm_store\fR() +and +\fIdbm_delete\fR() +functions shall return 0 when they succeed and a negative value when +they fail. +.P +The +\fIdbm_store\fR() +function shall return 1 if it is called with a +.IR flags +value of DBM_INSERT and the function finds an existing record with the +same key. +.P +The +\fIdbm_error\fR() +function shall return 0 if the error condition is not set and return a +non-zero value if the error condition is set. +.P +The return value of +\fIdbm_clearerr\fR() +is unspecified. +.P +The +\fIdbm_firstkey\fR() +and +\fIdbm_nextkey\fR() +functions shall return a key +.BR datum . +When the end of the database is reached, the +.IR dptr +member of the key is a null pointer. If an error is detected, the +.IR dptr +member of the key shall be a null pointer and the error condition of +the database shall be set. +.P +The +\fIdbm_fetch\fR() +function shall return a content +.BR datum . +If no record in the database matches the key or if an error condition +has been detected in the database, the +.IR dptr +member of the content shall be a null pointer. +.P +The +\fIdbm_open\fR() +function shall return a pointer to a database structure. If an error +is detected during the operation, +\fIdbm_open\fR() +shall return a (\c +.BR "DBM *" )0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The following code can be used to traverse the database: +.sp +.RS 4 +.nf + +for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db)) +.fi +.P +.RE +.P +The +.IR dbm_ * +functions provided in this library should not be confused in any way +with those of a general-purpose database management system. These +functions do not provide for multiple search keys per entry, they do +not protect against multi-user access (in other words they do not lock +records or files), and they do not provide the many other useful +database functions that are found in more robust database management +systems. Creating and updating databases by use of these functions is +relatively slow because of data copies that occur upon hash +collisions. These functions are useful for applications requiring fast +lookup of relatively static information that is to be indexed by a +single key. +.P +Note that a strictly conforming application is extremely limited by +these functions: since there is no way to determine that the keys in +use do not all hash to the same value (although that would be rare), a +strictly conforming application cannot be guaranteed that it can store +more than one block's worth of data in the database. As long as a key +collision does not occur, additional data may be stored, but because +there is no way to determine whether an error is due to a key collision +or some other error condition (\c +\fIdbm_error\fR() +being effectively a Boolean), once an error is detected, the +application is effectively limited to guessing what the error might be +if it wishes to continue using these functions. +.P +The +\fIdbm_delete\fR() +function need not physically reclaim file space, although it does make +it available for reuse by the database. +.P +After calling +\fIdbm_store\fR() +or +\fIdbm_delete\fR() +during a pass through the keys by +\fIdbm_firstkey\fR() +and +\fIdbm_nextkey\fR(), +the application should reset the database by calling +\fIdbm_firstkey\fR() +before again calling +\fIdbm_nextkey\fR(). +The contents of these files are unspecified and may not be portable. +.P +Applications should take care that database pathname arguments +specified to +\fIdbm_open\fR() +are not prefixes of unrelated files. This might be done, for example, +by placing databases in a separate directory. +.P +Since some implementations use three characters for a suffix and others +use four characters for a suffix, applications should ensure that the +maximum portable pathname length passed to +\fIdbm_open\fR() +is no greater than +{PATH_MAX}\-4 +bytes, with the last component of the pathname no greater than +{NAME_MAX}\-4 +bytes. +.SH RATIONALE +Previously the standard required the database to be stored in two +files, one file being a directory containing a bitmap of keys and +having +.BR .dir +as its suffix. The second file containing all data and having +.BR .pag +as its suffix. This has been changed not to specify the use of the +files and to allow newer implementations of the Berkeley DB interface +using a single file that have evolved while remaining compatible with +the application programming interface. The standard developers +considered removing the specific suffixes altogether but decided to +retain them so as not to pollute the application file name space more +than necessary and to allow for portable backups of the database. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/difftime.3p b/upstream/archlinux/man3p/difftime.3p new file mode 100644 index 00000000..2c6faafa --- /dev/null +++ b/upstream/archlinux/man3p/difftime.3p @@ -0,0 +1,80 @@ +'\" et +.TH DIFFTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +difftime +\(em compute the difference between two calendar time values +.SH SYNOPSIS +.LP +.nf +#include +.P +double difftime(time_t \fItime1\fP, time_t \fItime0\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIdifftime\fR() +function shall compute the difference between two calendar times (as +returned by +\fItime\fR()): +.IR time 1\- +.IR time 0. +.SH "RETURN VALUE" +The +\fIdifftime\fR() +function shall return the difference expressed in seconds as a type +.BR double . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dirfd.3p b/upstream/archlinux/man3p/dirfd.3p new file mode 100644 index 00000000..546a66a1 --- /dev/null +++ b/upstream/archlinux/man3p/dirfd.3p @@ -0,0 +1,124 @@ +'\" et +.TH DIRFD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dirfd +\(em extract the file descriptor used by a DIR stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int dirfd(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fIdirfd\fR() +function shall return a file descriptor referring to the same directory +as the +.IR dirp +argument. This file descriptor shall be closed by a call to +\fIclosedir\fR(). +If any attempt is made to close the file descriptor, or to modify the +state of the associated description, other than by means of +\fIclosedir\fR(), +\fIreaddir\fR(), +\fIreaddir_r\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(), +the behavior is undefined. +.SH "RETURN VALUE" +Upon successful completion, the +\fIdirfd\fR() +function shall return an integer which contains a file descriptor for +the stream pointed to by +.IR dirp . +Otherwise, it shall return \-1 and shall set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIdirfd\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR dirp +argument does not refer to a valid directory stream. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIdirfd\fR() +function is intended to be a mechanism by which an application may +obtain a file descriptor to use for the +\fIfchdir\fR() +function. +.SH RATIONALE +This interface was introduced because the Base Definitions volume of POSIX.1\(hy2017 does not make public +the +.BR DIR +data structure. Applications tend to use the +\fIfchdir\fR() +function on the file descriptor returned by this interface, and this +has proven useful for security reasons; in particular, it is a better +technique than others where directory names might change. +.P +The description uses the term ``a file descriptor'' rather than ``the +file descriptor''. The implication intended is that an implementation +that does not use an +.IR fd +for +\fIopendir\fR() +could still +\fIopen\fR() +the directory to implement the +\fIdirfd\fR() +function. Such a descriptor must be closed later during a call to +\fIclosedir\fR(). +.P +If it is necessary to allocate an +.IR fd +to be returned by +\fIdirfd\fR(), +it should be done at the time of a call to +\fIopendir\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIfchdir\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfileno\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dirname.3p b/upstream/archlinux/man3p/dirname.3p new file mode 100644 index 00000000..0c6a1ae4 --- /dev/null +++ b/upstream/archlinux/man3p/dirname.3p @@ -0,0 +1,174 @@ +'\" et +.TH DIRNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dirname +\(em report the parent directory name of a file pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +char *dirname(char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIdirname\fR() +function shall take a pointer to a character string that contains a +pathname, and return a pointer to a string that is a pathname of the +parent directory of that file. The +\fIdirname\fR() +function shall not perform pathname resolution; the result shall not be +affected by whether or not +.IR path +exists or by its file type. Trailing +.BR '/' +characters in the path that are not also leading +.BR '/' +characters shall not be counted as part of the path. +.P +If +.IR path +does not contain a +.BR '/' , +then +\fIdirname\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +If +.IR path +is a null pointer or points to an empty string, +\fIdirname\fR() +shall return a pointer to the string +.BR \(dq.\(dq . +.P +The +\fIdirname\fR() +function may modify the string pointed to by +.IR path , +and may return a pointer to static storage that may then be +overwritten by a subsequent call to +\fIdirname\fR(). +.P +The +\fIdirname\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIdirname\fR() +function shall return a pointer to a string as described above. +.P +The +\fIdirname\fR() +function may modify the string pointed to by +.IR path , +and may return a pointer to internal storage. The returned pointer +might be invalidated or the storage might be overwritten by a +subsequent call to +\fIdirname\fR(). +The returned pointer might also be invalidated if the calling +thread is terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following code fragment reads a pathname, changes the current +working directory to the parent directory, and opens the file. +.sp +.RS 4 +.nf + +char *path = NULL, *pathcopy; +size_t buflen = 0; +ssize_t linelen = 0; +int fd; +.P +linelen = getline(&path, &buflen, stdin); +.P +path[linelen-1] = 0; +pathcopy = strdup(path); +if (chdir(dirname(pathcopy)) < 0) { + ... +} +if ((fd = open(basename(path), O_RDONLY)) >= 0) { + ... + close (fd); +} +\&... +free (pathcopy); +free (path); +.fi +.P +.RE +.P +The EXAMPLES section of the +\fIbasename\fR() +function (see +.IR "\fIbasename\fR\^(\|)") +includes a table showing examples of the results of processing +several sample pathnames by the +\fIbasename\fR() +and +\fIdirname\fR() +functions and by the +.IR basename +and +.IR dirname +utilities. +.SH "APPLICATION USAGE" +The +\fIdirname\fR() +and +\fIbasename\fR() +functions together yield a complete pathname. The expression +\fIdirname\fP\^(\fIpath\fP) obtains the pathname of the directory where +\fIbasename\fP\^(\fIpath\fP) is found. +.P +Since the meaning of the leading +.BR \(dq//\(dq +is implementation-defined, +.IR dirname ("\c +.BR //foo ") +may return either +.BR \(dq//\(dq +or +.BR '/' +(but nothing else). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbasename\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIbasename\fR\^", +.IR "\fIdirname\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/div.3p b/upstream/archlinux/man3p/div.3p new file mode 100644 index 00000000..d7eded30 --- /dev/null +++ b/upstream/archlinux/man3p/div.3p @@ -0,0 +1,90 @@ +'\" et +.TH DIV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +div +\(em compute the quotient and remainder of an integer division +.SH SYNOPSIS +.LP +.nf +#include +.P +div_t div(int \fInumer\fP, int \fIdenom\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIdiv\fR() +function shall compute the quotient and remainder of the division +of the numerator +.IR numer +by the denominator +.IR denom . +If the division is inexact, the resulting quotient is the integer of +lesser magnitude that is the nearest to the algebraic quotient. If the +result cannot be represented, the behavior is undefined; otherwise, +.IR quot *\c +.IR denom +\c +.IR rem +shall equal +.IR numer . +.SH "RETURN VALUE" +The +\fIdiv\fR() +function shall return a structure of type +.BR div_t , +comprising both the quotient and the remainder. The structure includes +the following members, in any order: +.sp +.RS 4 +.nf + +int quot; /* quotient */ +int rem; /* remainder */ +.fi +.P +.RE +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIldiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dlclose.3p b/upstream/archlinux/man3p/dlclose.3p new file mode 100644 index 00000000..59ba1735 --- /dev/null +++ b/upstream/archlinux/man3p/dlclose.3p @@ -0,0 +1,143 @@ +'\" et +.TH DLCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dlclose +\(em close a symbol table handle +.SH SYNOPSIS +.LP +.nf +#include +.P +int dlclose(void *\fIhandle\fP); +.fi +.SH DESCRIPTION +The +\fIdlclose\fR() +function shall inform the system that the symbol table handle specified by +.IR handle +is no longer needed by the application. +.P +An application writer may use +\fIdlclose\fR() +to make a statement of intent on the part of the process, but this +statement does not create any requirement upon the implementation. When +the symbol table handle is closed, the implementation may unload the +executable object files that were loaded by +\fIdlopen\fR() +when the symbol table handle was opened and those that were loaded by +\fIdlsym\fR() +when using the symbol table handle identified by +.IR handle . +.P +Once a symbol table handle has been closed, an application should assume +that any symbols (function identifiers and data object identifiers) +made visible using +.IR handle , +are no longer available to the process. +.P +Although a +\fIdlclose\fR() +operation is not required to remove any functions or data objects from +the address space, neither is an implementation prohibited from doing +so. The only restriction on such a removal is that no function nor data +object shall be removed to which references have been relocated, until +or unless all such references are removed. For instance, an executable +object file that had been loaded with a +\fIdlopen\fR() +operation specifying the RTLD_GLOBAL flag might provide a target for +dynamic relocations performed in the processing of other relocatable +objects\(emin such environments, an application may assume that no +relocation, once made, shall be undone or remade unless the executable +object file containing the relocated object has itself been removed. +.SH "RETURN VALUE" +If the referenced symbol table handle was successfully closed, +\fIdlclose\fR() +shall return 0. If +.IR handle +does not refer to an open symbol table handle or if the symbol table +handle could not be closed, +\fIdlclose\fR() +shall return a non-zero value. More detailed diagnostic information +shall be available through +\fIdlerror\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example illustrates use of +\fIdlopen\fR() +and +\fIdlclose\fR(): +.sp +.RS 4 +.nf + +#include +int eret; +void *mylib; +\&... +/* Open a dynamic library and then close it ... */ +mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY); +\&... +eret = dlclose(mylib); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +A conforming application should employ a symbol table handle returned +from a +\fIdlopen\fR() +invocation only within a given scope bracketed by a +\fIdlopen\fR() +operation and the corresponding +\fIdlclose\fR() +operation. Implementations are free to use reference counting or other +techniques such that multiple calls to +\fIdlopen\fR() +referencing the same executable object file may return a pointer to the +same data object as the symbol table handle. +.P +Implementations are also free to re-use a handle. For these reasons, +the value of a handle must be treated as an opaque data type by the +application, used only in calls to +\fIdlsym\fR() +and +\fIdlclose\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dlerror.3p b/upstream/archlinux/man3p/dlerror.3p new file mode 100644 index 00000000..48560344 --- /dev/null +++ b/upstream/archlinux/man3p/dlerror.3p @@ -0,0 +1,112 @@ +'\" et +.TH DLERROR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dlerror +\(em get diagnostic information +.SH SYNOPSIS +.LP +.nf +#include +.P +char *dlerror(void); +.fi +.SH DESCRIPTION +The +\fIdlerror\fR() +function shall return a null-terminated character string (with no +trailing +) +that describes the last error that occurred during dynamic linking +processing. If no dynamic linking errors have occurred since the last +invocation of +\fIdlerror\fR(), +\fIdlerror\fR() +shall return NULL. +Thus, invoking +\fIdlerror\fR() +a second time, immediately following a prior invocation, shall result +in NULL being returned. +.P +It is implementation-defined whether or not the +\fIdlerror\fR() +function is thread-safe. A thread-safe implementation shall return only +errors that occur on the current thread. +.SH "RETURN VALUE" +If successful, +\fIdlerror\fR() +shall return a null-terminated character string; otherwise, NULL +shall be returned. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIdlerror\fR() +in the same thread (if +\fIdlerror\fR() +is thread-safe) or in any thread (if +\fIdlerror\fR() +is not thread-safe). The returned pointer might also be +invalidated if the calling thread is terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example prints out the last dynamic linking error: +.sp +.RS 4 +.nf + +\&... +#include +.P +char *errstr; +.P +errstr = dlerror(); +if (errstr != NULL) + printf ("A dynamic linking error occurred: (%s)\en", errstr); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Depending on the application environment with respect to asynchronous +execution events, such as signals or other asynchronous computation +sharing the address space, conforming applications should use a critical +section to retrieve the error pointer and buffer. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dlopen.3p b/upstream/archlinux/man3p/dlopen.3p new file mode 100644 index 00000000..b456570d --- /dev/null +++ b/upstream/archlinux/man3p/dlopen.3p @@ -0,0 +1,270 @@ +'\" et +.TH DLOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dlopen +\(em open a symbol table handle +.SH SYNOPSIS +.LP +.nf +#include +.P +void *dlopen(const char *\fIfile\fP, int \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIdlopen\fR() +function shall make the symbols (function identifiers and data object +identifiers) in the executable object file specified by +.IR file +available to the calling program. +.P +The class of executable object files eligible for this operation and +the manner of their construction are implementation-defined, though +typically such files are shared libraries or programs. +.P +Implementations may permit the construction of embedded dependencies in +executable object files. In such cases, a +\fIdlopen\fR() +operation shall load those dependencies in addition to the executable +object file specified by +.IR file . +Implementations may also impose specific constraints on the construction +of programs that can employ +\fIdlopen\fR() +and its related services. +.P +A successful +\fIdlopen\fR() +shall return a symbol table handle which the caller may use on subsequent +calls to +\fIdlsym\fR() +and +\fIdlclose\fR(). +.P +The value of this symbol table handle should not be interpreted in any +way by the caller. +.P +The +.IR file +argument is used to construct a pathname to the executable object file. If +.IR file +contains a + +character, the +.IR file +argument is used as the pathname for the file. Otherwise, +.IR file +is used in an implementation-defined manner to yield a pathname. +.P +If +.IR file +is a null pointer, +\fIdlopen\fR() +shall return a global symbol table handle for the currently running +process image. This symbol table handle shall provide access to the +symbols from an ordered set of executable object files consisting of +the original program image file, any executable object files loaded +at program start-up as specified by that process file (for example, +shared libraries), and the set of executable object files loaded using +\fIdlopen\fR() +operations with the RTLD_GLOBAL flag. As the latter set of executable +object files can change during execution, the set of symbols made +available by this symbol table handle can also change dynamically. +.P +Only a single copy of an executable object file shall be brought into +the address space, even if +\fIdlopen\fR() +is invoked multiple times in reference to the executable object file, +and even if different pathnames are used to reference the executable +object file. +.P +The +.IR mode +parameter describes how +\fIdlopen\fR() +shall operate upon +.IR file +with respect to the processing of relocations and the scope of visibility +of the symbols provided within +.IR file . +When an executable object file is brought into the address space of a +process, it may contain references to symbols whose addresses are not +known until the executable object file is loaded. +.P +These references shall be relocated before the symbols can be accessed. The +.IR mode +parameter governs when these relocations take place and may have the +following values: +.IP RTLD_LAZY 12 +Relocations shall be performed at an implementation-defined time, +ranging from the time of the +\fIdlopen\fR() +call until the first reference to a given symbol occurs. Specifying +RTLD_LAZY should improve performance on implementations supporting dynamic +symbol binding since a process might not reference all of the symbols +in an executable object file. And, for systems supporting dynamic symbol +resolution for normal process execution, this behavior mimics the normal +handling of process execution. +.IP RTLD_NOW 12 +All necessary relocations shall be performed when the executable object +file is first loaded. This may waste some processing if relocations are +performed for symbols that are never referenced. This behavior may be +useful for applications that need to know that all symbols referenced +during execution will be available before +\fIdlopen\fR() +returns. +.P +Any executable object file loaded by +\fIdlopen\fR() +that requires relocations against global symbols can reference the symbols +in the original process image file, any executable object files loaded +at program start-up, from the initial process image itself, from any +other executable object file included in the same +\fIdlopen\fR() +invocation, and any executable object files that were loaded in any +\fIdlopen\fR() +invocation and which specified the RTLD_GLOBAL flag. To determine the +scope of visibility for the symbols loaded with a +\fIdlopen\fR() +invocation, the +.IR mode +parameter should be a bitwise-inclusive OR with one of the following +values: +.IP RTLD_GLOBAL 12 +The executable object file's symbols shall be made available for +relocation processing of any other executable object file. In addition, +symbol lookup using +.IR dlopen (NULL, mode ) +and an associated +\fIdlsym\fR() +allows executable object files loaded with this mode to be searched. +.IP RTLD_LOCAL 12 +The executable object file's symbols shall not be made available for +relocation processing of any other executable object file. +.P +If neither RTLD_GLOBAL nor RTLD_LOCAL is specified, the default behavior +is unspecified. +.P +If an executable object file is specified in multiple +\fIdlopen\fR() +invocations, +.IR mode +is interpreted at each invocation. +.P +If RTLD_NOW has been specified, all relocations shall have been completed +rendering further RTLD_NOW operations redundant and any further RTLD_LAZY +operations irrelevant. +.P +If RTLD_GLOBAL has been specified, the executable object file shall +maintain the RTLD_GLOBAL status regardless of any previous or future +specification of RTLD_LOCAL, as long as the executable object file +remains in the address space (see +.IR "\fIdlclose\fR\^(\|)"). +.P +Symbols introduced into the process image through calls to +\fIdlopen\fR() +may be used in relocation activities. Symbols so introduced may duplicate +symbols already defined by the program or previous +\fIdlopen\fR() +operations. To resolve the ambiguities such a situation might present, +the resolution of a symbol reference to symbol definition is based on a +symbol resolution order. Two such resolution orders are defined: load +order and dependency order. Load order establishes an ordering among +symbol definitions, such that the first definition loaded (including +definitions from the process image file and any dependent executable +object files loaded with it) has priority over executable object files +added later (by +\fIdlopen\fR()). +Load ordering is used in relocation processing. Dependency ordering uses +a breadth-first order starting with a given executable object file, +then all of its dependencies, then any dependents of those, iterating +until all dependencies are satisfied. With the exception of the global +symbol table handle obtained via a +\fIdlopen\fR() +operation with a null pointer as the +.IR file +argument, dependency ordering is used by the +\fIdlsym\fR() +function. Load ordering is used in +\fIdlsym\fR() +operations upon the global symbol table handle. +.P +When an executable object file is first made accessible via +\fIdlopen\fR(), +it and its dependent executable object files are added in dependency +order. Once all the executable object files are added, relocations are +performed using load order. Note that if an executable object file or +its dependencies had been previously loaded, the load and dependency +orders may yield different resolutions. +.P +The symbols introduced by +\fIdlopen\fR() +operations and available through +\fIdlsym\fR() +are at a minimum those which are exported as identifiers of global +scope by the executable object file. Typically, such identifiers shall +be those that were specified in (for example) C source code as having +.BR extern +linkage. The precise manner in which an implementation constructs +the set of exported symbols for an executable object file is +implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, +\fIdlopen\fR() +shall return a symbol table handle. If +.IR file +cannot be found, cannot be opened for reading, is not of an appropriate +executable object file format for processing by +\fIdlopen\fR(), +or if an error occurs during the process of loading +.IR file +or relocating its symbolic references, +\fIdlopen\fR() +shall return a null pointer. More detailed diagnostic information shall +be available through +\fIdlerror\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Refer to +.IR "\fIdlsym\fR\^(\|)". +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlsym\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dlsym.3p b/upstream/archlinux/man3p/dlsym.3p new file mode 100644 index 00000000..474b2bae --- /dev/null +++ b/upstream/archlinux/man3p/dlsym.3p @@ -0,0 +1,192 @@ +'\" et +.TH DLSYM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dlsym +\(em get the address of a symbol from a symbol table handle +.SH SYNOPSIS +.LP +.nf +#include +.P +void *dlsym(void *restrict \fIhandle\fP, const char *restrict \fIname\fP); +.fi +.SH DESCRIPTION +The +\fIdlsym\fR() +function shall obtain the address of a symbol (a function identifier or +a data object identifier) defined in the symbol table identified by the +.IR handle +argument. The +.IR handle +argument is a symbol table handle returned from a call to +\fIdlopen\fR() +(and which has not since been released by a call to +\fIdlclose\fR()), +and +.IR name +is the symbol's name as a character string. The return value from +\fIdlsym\fR(), +cast to a pointer to the type of the named symbol, can be used to call +(in the case of a function) or access the contents of (in the case of +a data object) the named symbol. +.P +The +\fIdlsym\fR() +function shall search for the named symbol in the symbol table +referenced by +.IR handle . +If the symbol table was created with lazy loading +(see RTLD_LAZY in +\fIdlopen\fR()), +load ordering shall be used in +\fIdlsym\fR() +operations to relocate executable object files needed to resolve the +symbol. The symbol resolution algorithm used shall be dependency order +as described in +\fIdlopen\fR(). +.P +The RTLD_DEFAULT and RTLD_NEXT symbolic constants (which may be defined in +.IR ) +are reserved for future use as special values that applications may be +allowed to use for +.IR handle . +.SH "RETURN VALUE" +Upon successful completion, if +.IR name +names a function identifier, +\fIdlsym\fR() +shall return the address of the function converted from type pointer to +function to type pointer to +.BR void ; +otherwise, +\fIdlsym\fR() +shall return the address of the data object associated with the data +object identifier named by +.IR name +converted from a pointer to the type of the data object to a pointer to +.BR void . +If +.IR handle +does not refer to a valid symbol table handle or if the symbol named by +.IR name +cannot be found in the symbol table associated with +.IR handle , +\fIdlsym\fR() +shall return a null pointer. +.P +More detailed diagnostic information shall be available through +\fIdlerror\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following example shows how +\fIdlopen\fR() +and +\fIdlsym\fR() +can be used to access either a function or a data object. For simplicity, +error checking has been omitted. +.sp +.RS 4 +.nf + +void *handle; +int (*fptr)(int), *iptr, result; +/* open the needed symbol table */ +handle = dlopen("/usr/home/me/libfoo.so", RTLD_LOCAL | RTLD_LAZY); +/* find the address of the function my_function */ +fptr = (int (*)(int))dlsym(handle, "my_function"); +/* find the address of the data object my_object */ +iptr = (int *)dlsym(handle, "my_OBJ"); +/* invoke my_function, passing the value of my_OBJ as the parameter */ +result = (*fptr)(*iptr); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The following special purpose values for +.IR handle +are reserved for future use and have the indicated meanings: +.IP RTLD_DEFAULT 12 +The identifier lookup happens in the normal global scope; that is, +a search for an identifier using +.IR handle +would find the same definition as a direct use of this identifier in +the program code. +.IP RTLD_NEXT 12 +Specifies the next executable object file after this one that defines +.IR name . +This one refers to the executable object file containing the invocation of +\fIdlsym\fR(). +The next executable object file is the one found upon the application +of a load order symbol resolution algorithm (see +\fIdlopen\fR()). +The next symbol is either one of global scope (because it was introduced +as part of the original process image or because it was added with a +\fIdlopen\fR() +operation including the RTLD_GLOBAL flag), or is in an executable object +file that was included in the same +\fIdlopen\fR() +operation that loaded this one. +.P +The RTLD_NEXT flag is useful to navigate an intentionally created +hierarchy of multiply-defined symbols created through interposition. For +example, if a program wished to create an implementation of +\fImalloc\fR() +that embedded some statistics gathering about memory allocations, such +an implementation could use the real +\fImalloc\fR() +definition to perform the memory allocation \(em and itself only embed +the necessary logic to implement the statistics gathering function. +.P +Note that conversion from a +.BR "void *" +pointer to a function pointer as in: +.sp +.RS 4 +.nf + +fptr = (int (*)(int))dlsym(handle, "my_function"); +.fi +.P +.RE +.P +is not defined by the ISO\ C standard. This standard requires this conversion to +work correctly on conforming implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdlclose\fR\^(\|)", +.IR "\fIdlerror\fR\^(\|)", +.IR "\fIdlopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dprintf.3p b/upstream/archlinux/man3p/dprintf.3p new file mode 100644 index 00000000..69794674 --- /dev/null +++ b/upstream/archlinux/man3p/dprintf.3p @@ -0,0 +1,39 @@ +'\" et +.TH DPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dprintf \(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int dprintf(int \fIfildes\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/drand48.3p b/upstream/archlinux/man3p/drand48.3p new file mode 100644 index 00000000..71579711 --- /dev/null +++ b/upstream/archlinux/man3p/drand48.3p @@ -0,0 +1,244 @@ +'\" et +.TH DRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.EQ +delim $$ +.EN +.SH NAME +drand48, +erand48, +jrand48, +lcong48, +lrand48, +mrand48, +nrand48, +seed48, +srand48 +\(em generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double drand48(void); +double erand48(unsigned short \fIxsubi\fP[3]); +long jrand48(unsigned short \fIxsubi\fP[3]); +void lcong48(unsigned short \fIparam\fP[7]); +long lrand48(void); +long mrand48(void); +long nrand48(unsigned short \fIxsubi\fP[3]); +unsigned short *seed48(unsigned short \fIseed16v\fP[3]); +void srand48(long \fIseedval\fP); +.fi +.SH DESCRIPTION +This family of functions shall generate pseudo-random numbers using +a linear congruential algorithm and 48-bit integer arithmetic. +.P +The +\fIdrand48\fR() +and +\fIerand48\fR() +functions shall return non-negative, double-precision, floating-point +values, uniformly distributed over the interval [0.0,1.0). +.P +The +\fIlrand48\fR() +and +\fInrand48\fR() +functions shall return non-negative, long integers, uniformly +distributed over the interval [0,2\u\s-331\s+3\d). +.P +The +\fImrand48\fR() +and +\fIjrand48\fR() +functions shall return signed long integers uniformly distributed over +the interval [\-2\u\s-331\s+3\d,2\u\s-331\s+3\d). +.P +The +\fIsrand48\fR(), +\fIseed48\fR(), +and +\fIlcong48\fR() +functions are initialization entry points, one of which should be +invoked before either +\fIdrand48\fR(), +\fIlrand48\fR(), +or +\fImrand48\fR() +is called. (Although it is not recommended practice, constant default +initializer values shall be supplied automatically if +\fIdrand48\fR(), +\fIlrand48\fR(), +or +\fImrand48\fR() +is called without a prior call to an initialization entry point.) The +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +functions do not require an initialization entry point to be called +first. +.P +All the routines work by generating a sequence of 48-bit integer +values, $X_ i" " ,$ according to the linear congruential formula: +.sp +.RS +$X sub{n+1} " " = " " (aX_ n" "^+^c) sub{roman mod " " m} " " " " " " " " " " " " " " " " n>= " " 0$ +.RE +.P +The parameter $m^=^2"^" 48$; hence 48-bit integer arithmetic is +performed. Unless +\fIlcong48\fR() +is invoked, the multiplier value $a$ and the addend value $c$ are given +by: +.sp +.RS +$a " " mark = " " roman "5DEECE66D"^sub 16 " " = " " roman 273673163155^sub 8$ +.P +$c " " lineup = " " roman B^sub 16 " " = " " roman 13^sub 8$ +.RE +.P +The value returned by any of the +\fIdrand48\fR(), +\fIerand48\fR(), +\fIjrand48\fR(), +\fIlrand48\fR(), +\fImrand48\fR(), +or +\fInrand48\fR() +functions is computed by first generating the next 48-bit $X_ i$ in +the sequence. Then the appropriate number of bits, according to the +type of data item to be returned, are copied from the high-order +(leftmost) bits of $X_ i$ and transformed into the returned value. +.P +The +\fIdrand48\fR(), +\fIlrand48\fR(), +and +\fImrand48\fR() +functions store the last 48-bit $X_ i$ generated in an internal +buffer; that is why the application shall ensure that these are +initialized prior to being invoked. The +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +functions require the calling program to provide storage for the +successive $X_ i$ values in the array specified as an argument when +the functions are invoked. That is why these routines do not have to +be initialized; the calling program merely has to place the desired +initial value of $X_ i$ into the array and pass it as an argument. +By using different arguments, +\fIerand48\fR(), +\fInrand48\fR(), +and +\fIjrand48\fR() +allow separate modules of a large program to generate several +.IR independent +streams of pseudo-random numbers; that is, the sequence of numbers in +each stream shall +.IR not +depend upon how many times the routines are called to generate numbers +for the other streams. +.P +The initializer function +\fIsrand48\fR() +sets the high-order 32 bits of $X_ i$ to the low-order 32 bits +contained in its argument. The low-order 16 bits of $X_ i$ are set +to the arbitrary value $roman 330E_ 16" " .$ +.P +The initializer function +\fIseed48\fR() +sets the value of $X_ i$ to the 48-bit value specified in the +argument array. The low-order 16 bits of $X_ i$ are set to the +low-order 16 bits of +.IR seed16v [ 0 ]. +The mid-order 16 bits of $X_ i$ are set to the low-order 16 bits of +.IR seed16v [ 1 ]. +The high-order 16 bits of $X_ i$ are set to the low-order 16 bits of +.IR seed16v [ 2 ]. +In addition, the previous value of $X_ i$ is copied into a 48-bit +internal buffer, used only by +\fIseed48\fR(), +and a pointer to this buffer is the value returned by +\fIseed48\fR(). +This returned pointer, which can just be ignored if not needed, is +useful if a program is to be restarted from a given point at some +future time\(emuse the pointer to get at and store the last $X_ i$ +value, and then use this value to reinitialize via +\fIseed48\fR() +when the program is restarted. +.P +The initializer function +\fIlcong48\fR() +allows the user to specify the initial $X_ i" " ,$ the multiplier value +$a,$ and the addend value $c.$ Argument array elements +.IR param [ 0-2 ] +specify $X_ i" " ,$ +.IR param [ 3-5 ] +specify the multiplier $a,$ and +.IR param [ 6 ] +specifies the 16-bit addend $c.$ After +\fIlcong48\fR() +is called, a subsequent call to either +\fIsrand48\fR() +or +\fIseed48\fR() +shall restore the standard multiplier and addend values, +.IR a +and +.IR c, +specified above. +.P +The +\fIdrand48\fR(), +\fIlrand48\fR(), +and +\fImrand48\fR() +functions need not be thread-safe. +.SH "RETURN VALUE" +As described in the DESCRIPTION above. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions should be avoided whenever non-trivial +requirements (including safety) have to be fulfilled. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIinitstate\fR\^(\|)", +.IR "\fIrand\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/dup.3p b/upstream/archlinux/man3p/dup.3p new file mode 100644 index 00000000..59444c3f --- /dev/null +++ b/upstream/archlinux/man3p/dup.3p @@ -0,0 +1,264 @@ +'\" et +.TH DUP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dup, +dup2 +\(em duplicate an open file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int dup(int \fIfildes\fP); +int dup2(int \fIfildes\fP, int \fIfildes2\fP); +.fi +.SH DESCRIPTION +The +\fIdup\fR() +function provides an alternative interface to the service provided by +\fIfcntl\fR() +using the F_DUPFD command. The call +.IR dup ( fildes ) +shall be equivalent to: +.sp +.RS 4 +.nf + +fcntl(fildes, F_DUPFD, 0); +.fi +.P +.RE +.P +The +\fIdup2\fR() +function shall cause the file descriptor +.IR fildes2 +to refer to the same open file description as the file descriptor +.IR fildes +and to share any locks, and shall return +.IR fildes2 . +If +.IR fildes2 +is already a valid open file descriptor, it shall be closed first, unless +.IR fildes +is equal to +.IR fildes2 +in which case +\fIdup2\fR() +shall return +.IR fildes2 +without closing it. If the close operation fails to close +.IR fildes2 , +\fIdup2\fR() +shall return \-1 without changing the open file description to which +.IR fildes2 +refers. If +.IR fildes +is not a valid file descriptor, +\fIdup2\fR() +shall return \-1 and shall not close +.IR fildes2 . +If +.IR fildes2 +is less than 0 or greater than or equal to +{OPEN_MAX}, +\fIdup2\fR() +shall return \-1 with +.IR errno +set to +.BR [EBADF] . +.P +Upon successful completion, if +.IR fildes +is not equal to +.IR fildes2 , +the FD_CLOEXEC flag associated with +.IR fildes2 +shall be cleared. If +.IR fildes +is equal to +.IR fildes2 , +the FD_CLOEXEC flag associated with +.IR fildes2 +shall not be changed. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIdup2\fR() +function is unspecified. +.SH "RETURN VALUE" +Upon successful completion a non-negative integer, namely the file +descriptor, shall be returned; otherwise, \-1 shall be returned +and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIdup\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.P +The +\fIdup2\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor or the argument +.IR fildes2 +is negative or greater than or equal to +{OPEN_MAX}. +.TP +.BR EINTR +The +\fIdup2\fR() +function was interrupted by a signal. +.P +The +\fIdup2\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while attempting to close +.IR fildes2 . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Redirecting Standard Output to a File" S +.P +The following example closes standard output for the current processes, +re-assigns standard output to go to the file referenced by +.IR pfd , +and closes the original file descriptor to clean up. +.sp +.RS 4 +.nf + +#include +\&... +int pfd; +\&... +close(1); +dup(pfd); +close(pfd); +\&... +.fi +.P +.RE +.SS "Redirecting Error Messages" +.P +The following example redirects messages from +.IR stderr +to +.IR stdout . +.sp +.RS 4 +.nf + +#include +\&... +dup2(1, 2); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIdup2\fR() +with an arbitrary integer for +.IR fildes2 +risks non-conforming behavior, and +\fIdup2\fR() +can only portably be used to overwrite file descriptor values that the +application has obtained through explicit actions, or for the three file +descriptors corresponding to the standard file streams. In order to avoid +a race condition of leaking an unintended file descriptor into a child +process, an application should consider opening all file descriptors +with the FD_CLOEXEC bit set unless the file descriptor is intended to +be inherited across +.IR exec . +.SH RATIONALE +The +\fIdup\fR() +function is redundant. Its services are also provided by the +\fIfcntl\fR() +function. It has been included in this volume of POSIX.1\(hy2017 primarily for historical reasons, +since many existing applications use it. On the other hand, the +\fIdup2\fR() +function provides unique services, as no other interface is able to +atomically replace an existing file descriptor. +.P +The +\fIdup2\fR() +function is not marked obsolescent because it presents a type-safe +version of functionality provided in a type-unsafe version by +\fIfcntl\fR(). +It is used in the POSIX Ada binding. +.P +The +\fIdup2\fR() +function is not intended for use in critical regions as a +synchronization mechanism. +.P +In the description of +.BR [EBADF] , +the case of +.IR fildes +being out of range is covered by the given case of +.IR fildes +not being valid. The descriptions for +.IR fildes +and +.IR fildes2 +are different because the only kind of invalidity that is relevant for +.IR fildes2 +is whether it is out of range; that is, it does not matter whether +.IR fildes2 +refers to an open file when the +\fIdup2\fR() +call is made. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/duplocale.3p b/upstream/archlinux/man3p/duplocale.3p new file mode 100644 index 00000000..b158a1a3 --- /dev/null +++ b/upstream/archlinux/man3p/duplocale.3p @@ -0,0 +1,152 @@ +'\" et +.TH DUPLOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +duplocale +\(em duplicate a locale object +.SH SYNOPSIS +.LP +.nf +#include +.P +locale_t duplocale(locale_t \fIlocobj\fP); +.fi +.SH DESCRIPTION +The +\fIduplocale\fR() +function shall create a duplicate copy of the locale object referenced +by the +.IR locobj +argument. +.P +If the +.IR locobj +argument is LC_GLOBAL_LOCALE, +\fIduplocale\fR() +shall create a new locale object containing a copy of the global locale +determined by the +\fIsetlocale\fR() +function. +.P +The behavior is undefined if the +.IR locobj +argument is not a valid locale object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fIduplocale\fR() +function shall return a handle for a new locale object. Otherwise, +\fIduplocale\fR() +shall return (\c +.BR locale_t )0 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIduplocale\fR() +function shall fail if: +.TP +.BR ENOMEM +There is not enough memory available to create the locale object or +load the locale data. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Constructing an Altered Version of an Existing Locale Object" +.P +The following example shows a code fragment to create a slightly +altered version of an existing locale object. The function takes a +locale object and a locale name and it replaces the +.IR LC_TIME +category data in the locale object with that from the named locale. +.sp +.RS 4 +.nf + +#include +\&... +.P +locale_t +with_changed_lc_time (locale_t obj, const char *name) +{ +.P + locale_t retval = duplocale (obj); + if (retval != (locale_t) 0) + { + locale_t changed = newlocale (LC_TIME_MASK, name, retval); + if (changed == (locale_t) 0) + /* An error occurred. Free all allocated resources. */ + freelocale (retval); + retval = changed; + } + return retval; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The use of the +\fIduplocale\fR() +function is recommended for situations where a locale object is being +used in multiple places, and it is possible that the lifetime of the +locale object might end before all uses are finished. Another reason to +duplicate a locale object is if a slightly modified form is needed. +This can be achieved by a call to +\fInewlocale\fR() +following the +\fIduplocale\fR() +call. +.P +As with the +\fInewlocale\fR() +function, handles for locale objects created by the +\fIduplocale\fR() +function should be released by a corresponding call to +\fIfreelocale\fR(). +.P +The +\fIduplocale\fR() +function can also be used in conjunction with +.IR uselocale ((\c +.BR locale_t )0). +This returns the locale in effect for the calling thread, but can have +the value LC_GLOBAL_LOCALE. Passing LC_GLOBAL_LOCALE to functions such as +\fIisalnum_l\fR() +results in undefined behavior, but applications can convert it into a +usable locale object by using +\fIduplocale\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/encrypt.3p b/upstream/archlinux/man3p/encrypt.3p new file mode 100644 index 00000000..b791cd9e --- /dev/null +++ b/upstream/archlinux/man3p/encrypt.3p @@ -0,0 +1,121 @@ +'\" et +.TH ENCRYPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +encrypt +\(em encoding function +(\fBCRYPT\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +void encrypt(char \fIblock\fP[64], int \fIedflag\fP); +.fi +.SH DESCRIPTION +The +\fIencrypt\fR() +function shall provide access to an implementation-defined encoding +algorithm. The key generated by +\fIsetkey\fR() +is used to encrypt the string +.IR block +with +\fIencrypt\fR(). +.P +The +.IR block +argument to +\fIencrypt\fR() +shall be an array of length 64 bytes containing only the bytes with +values of 0 and 1. The array is modified in place to a similar +array using the key set by +\fIsetkey\fR(). +If +.IR edflag +is 0, the argument is encoded. If +.IR edflag +is 1, the argument may be decoded (see the APPLICATION USAGE section); +if the argument is not decoded, +.IR errno +shall be set to +.BR [ENOSYS] . +.P +The +\fIencrypt\fR() +function shall not change the setting of +.IR errno +if successful. An application wishing to check for error situations +should set +.IR errno +to 0 before calling +\fIencrypt\fR(). +If +.IR errno +is non-zero on return, an error has occurred. +.P +The +\fIencrypt\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIencrypt\fR() +function shall not return a value. +.SH ERRORS +The +\fIencrypt\fR() +function shall fail if: +.TP +.BR ENOSYS +The functionality is not supported on this implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Historical implementations of the +\fIencrypt\fR() +function used a rather primitive encoding algorithm. +.P +In some environments, decoding might not be implemented. This is +related to some Government restrictions on encryption and decryption +routines. Historical practice has been to ship a different version of +the encryption library without the decryption feature in the routines +supplied. Thus the exported version of +\fIencrypt\fR() +does encoding but not decoding. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version of the standard may mark this interface as +obsolete or remove it altogether. +.SH "SEE ALSO" +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIsetkey\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/endgrent.3p b/upstream/archlinux/man3p/endgrent.3p new file mode 100644 index 00000000..68a052de --- /dev/null +++ b/upstream/archlinux/man3p/endgrent.3p @@ -0,0 +1,174 @@ +'\" et +.TH ENDGRENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +endgrent, +getgrent, +setgrent +\(em group database entry functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endgrent(void); +struct group *getgrent(void); +void setgrent(void); +.fi +.SH DESCRIPTION +The +\fIgetgrent\fR() +function shall return a pointer to a structure containing the broken-out +fields of an entry in the group database. If the group database +is not already open, +\fIgetgrent\fR() +shall open it and return a pointer to a +.BR group +structure containing the first entry in the database. Thereafter, +it shall return a pointer to a +.BR group +structure containing the next +.BR group +structure in the group database, so successive calls may be used +to search the entire database. +.P +An implementation that provides extended security controls may impose +further implementation-defined restrictions on accessing the group +database. In particular, the system may deny the existence of some or +all of the group database entries associated with groups other than +those groups associated with the caller and may omit users other than +the caller from the list of members of groups in database entries that +are returned. +.P +The +\fIsetgrent\fR() +function shall rewind the group database so that the next +\fIgetgrent\fR() +call returns the first entry, allowing repeated searches. +.P +The +\fIendgrent\fR() +function shall close the group database. +.P +The +\fIsetgrent\fR() +and +\fIendgrent\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +On error, the +\fIsetgrent\fR() +and +\fIendgrent\fR() +functions shall set +.IR errno +to indicate the error. +.P +Since no value is returned by the +\fIsetgrent\fR() +and +\fIendgrent\fR() +functions, an application wishing to check for error situations +should set +.IR errno +to 0, then call the function, then check +.IR errno . +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +On successful completion, +\fIgetgrent\fR() +shall return a pointer to a +.BR group +structure. On end-of-file, +\fIgetgrent\fR() +shall return a null pointer and shall not change the setting of +.IR errno . +On error, +\fIgetgrent\fR() +shall return a null pointer and +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetgrgid\fR(), +\fIgetgrnam\fR(), +or +\fIgetgrent\fR(). +The returned pointer, and pointers within the structure, might +also be invalidated if the calling thread is terminated. +.SH ERRORS +These functions may fail if: +.TP +.BR EINTR +A signal was caught during the operation. +.TP +.BR EIO +An I/O error has occurred. +.P +In addition, the +\fIgetgrent\fR() +and +\fIsetgrent\fR() +functions may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are provided due to their historical usage. +Applications should avoid dependencies on fields in the group database, +whether the database is a single file, or where in the file system +name space the database resides. Applications should use +\fIgetgrnam\fR() +and +\fIgetgrgid\fR() +whenever possible because it avoids these dependencies. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendpwent\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIgetgrnam\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/endhostent.3p b/upstream/archlinux/man3p/endhostent.3p new file mode 100644 index 00000000..74975d2d --- /dev/null +++ b/upstream/archlinux/man3p/endhostent.3p @@ -0,0 +1,113 @@ +'\" et +.TH ENDHOSTENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +endhostent, +gethostent, +sethostent +\(em network host database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endhostent(void); +struct hostent *gethostent(void); +void sethostent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about hosts. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.TP 10 +.BR Note: +In many cases this database is implemented by the Domain Name System, +as documented in RFC\ 1034, RFC\ 1035, and RFC\ 1886. +.P +.P +The +\fIsethostent\fR() +function shall open a connection to the database and set the next entry +for retrieval to the first entry in the database. If the +.IR stayopen +argument is non-zero, the connection shall not be closed by a call to +\fIgethostent\fR(), +and the implementation may maintain an open file descriptor. +.P +The +\fIgethostent\fR() +function shall read the next entry in the database, opening and closing +a connection to the database as necessary. +.P +Entries shall be returned in +.BR hostent +structures. +.P +The +\fIendhostent\fR() +function shall close the connection to the database, releasing any open +file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, the +\fIgethostent\fR() +function shall return a pointer to a +.BR hostent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgethostent\fR(). +The returned pointer, and pointers within the structure, might also +be invalidated if the calling thread is terminated. +.SH ERRORS +No errors are defined for +\fIendhostent\fR(), +\fIgethostent\fR(), +and +\fIsethostent\fR(). +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendservent\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/endnetent.3p b/upstream/archlinux/man3p/endnetent.3p new file mode 100644 index 00000000..0a075f2d --- /dev/null +++ b/upstream/archlinux/man3p/endnetent.3p @@ -0,0 +1,147 @@ +'\" et +.TH ENDNETENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +endnetent, +getnetbyaddr, +getnetbyname, +getnetent, +setnetent +\(em network database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endnetent(void); +struct netent *getnetbyaddr(uint32_t \fInet\fP, int \fItype\fP); +struct netent *getnetbyname(const char *\fIname\fP); +struct netent *getnetent(void); +void setnetent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about networks. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.P +The +\fIsetnetent\fR() +function shall open and rewind the database. If the +.IR stayopen +argument is non-zero, the connection to the +.IR net +database shall not be closed after each call to +\fIgetnetent\fR() +(either directly, or indirectly through one of the other +.IR getnet* (\|) +functions), and the implementation may maintain an open file descriptor +to the database. +.P +The +\fIgetnetent\fR() +function shall read the next entry of the database, opening and +closing a connection to the database as necessary. +.P +The +\fIgetnetbyaddr\fR() +function shall search the database from the beginning, and find the +first entry for which the address family specified by +.IR type +matches the +.IR n_addrtype +member and the network number +.IR net +matches the +.IR n_net +member, opening and closing a connection to the database as necessary. +The +.IR net +argument shall be the network number in host byte order. +.P +The +\fIgetnetbyname\fR() +function shall search the database from the beginning and find the +first entry for which the network name specified by +.IR name +matches the +.IR n_name +member, opening and closing a connection to the database as necessary. +.P +The +\fIgetnetbyaddr\fR(), +\fIgetnetbyname\fR(), +and +\fIgetnetent\fR() +functions shall each return a pointer to a +.BR netent +structure, the members of which shall contain the fields of an entry in +the network database. +.P +The +\fIendnetent\fR() +function shall close the database, releasing any open file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetnetbyaddr\fR(), +\fIgetnetbyname\fR(), +and +\fIgetnetent\fR() +shall return a pointer to a +.BR netent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +Otherwise, a null pointer shall be returned. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetnetbyaddr\fR(), +\fIgetnetbyname\fR(), +or +\fIgetnetent\fR(). +The returned pointer, and pointers within the structure, might also be +invalidated if the calling thread is terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/endprotoent.3p b/upstream/archlinux/man3p/endprotoent.3p new file mode 100644 index 00000000..f7c46d95 --- /dev/null +++ b/upstream/archlinux/man3p/endprotoent.3p @@ -0,0 +1,141 @@ +'\" et +.TH ENDPROTOENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +endprotoent, +getprotobyname, +getprotobynumber, +getprotoent, +setprotoent +\(em network protocol database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endprotoent(void); +struct protoent *getprotobyname(const char *\fIname\fP); +struct protoent *getprotobynumber(int \fIproto\fP); +struct protoent *getprotoent(void); +void setprotoent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about protocols. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.P +The +\fIsetprotoent\fR() +function shall open a connection to the database, and set the next +entry to the first entry. If the +.IR stayopen +argument is non-zero, the connection to the network protocol database +shall not be closed after each call to +\fIgetprotoent\fR() +(either directly, or indirectly through one of the other +.IR getproto* (\|) +functions), and the implementation may maintain an open file descriptor +for the database. +.P +The +\fIgetprotobyname\fR() +function shall search the database from the beginning and find the +first entry for which the protocol name specified by +.IR name +matches the +.IR p_name +member, opening and closing a connection to the database as necessary. +.P +The +\fIgetprotobynumber\fR() +function shall search the database from the beginning and find the +first entry for which the protocol number specified by +.IR proto +matches the +.IR p_proto +member, opening and closing a connection to the database as necessary. +.P +The +\fIgetprotoent\fR() +function shall read the next entry of the database, opening and closing +a connection to the database as necessary. +.P +The +\fIgetprotobyname\fR(), +\fIgetprotobynumber\fR(), +and +\fIgetprotoent\fR() +functions shall each return a pointer to a +.BR protoent +structure, the members of which shall contain the fields of an entry in +the network protocol database. +.P +The +\fIendprotoent\fR() +function shall close the connection to the database, releasing any +open file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetprotobyname\fR(), +\fIgetprotobynumber\fR(), +and +\fIgetprotoent\fR() +return a pointer to a +.BR protoent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +Otherwise, a null pointer is returned. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetprotobyname\fR(), +\fIgetprotobynumber\fR(), +or +\fIgetprotoent\fR(). +The returned pointer, and pointers within the structure, might also be +invalidated if the calling thread is terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/endpwent.3p b/upstream/archlinux/man3p/endpwent.3p new file mode 100644 index 00000000..1fa549d2 --- /dev/null +++ b/upstream/archlinux/man3p/endpwent.3p @@ -0,0 +1,208 @@ +'\" et +.TH ENDPWENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +endpwent, +getpwent, +setpwent +\(em user database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endpwent(void); +struct passwd *getpwent(void); +void setpwent(void); +.fi +.SH DESCRIPTION +These functions shall retrieve information about users. +.P +The +\fIgetpwent\fR() +function shall return a pointer to a structure containing the broken-out +fields of an entry in the user database. Each entry in the user +database contains a +.BR passwd +structure. If the user database is not already open, +\fIgetpwent\fR() +shall open it and return a pointer to a +.BR passwd +structure containing the first entry in the database. Thereafter, +it shall return a pointer to a +.BR passwd +structure containing the next entry in the user database. Successive +calls can be used to search the entire user database. +.P +If an end-of-file or an error is encountered on reading, +\fIgetpwent\fR() +shall return a null pointer. +.P +An implementation that provides extended security controls may impose +further implementation-defined restrictions on accessing the user +database. In particular, the system may deny the existence of some or +all of the user database entries associated with users other than the +caller. +.P +The +\fIsetpwent\fR() +function shall rewind the user database so that the next +\fIgetpwent\fR() +call returns the first entry, allowing repeated searches. +.P +The +\fIendpwent\fR() +function shall close the user database. +.P +The +\fIsetpwent\fR() +and +\fIendpwent\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +On error, the +\fIsetpwent\fR() +and +\fIendpwent\fR() +functions shall set +.IR errno +to indicate the error. +.P +Since no value is returned by the +\fIsetpwent\fR() +and +\fIendpwent\fR() +functions, an application wishing to check for error situations +should set +.IR errno +to 0, then call the function, then check +.IR errno . +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +On successful completion, +\fIgetpwent\fR() +shall return a pointer to a +.BR passwd +structure. On end-of-file, +\fIgetpwent\fR() +shall return a null pointer and shall not change the setting of +.IR errno . +On error, +\fIgetpwent\fR() +shall return a null pointer and +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetpwuid\fR(), +\fIgetpwnam\fR(), +or +\fIgetpwent\fR(). +The returned pointer, and pointers within the structure, might also +be invalidated if the calling thread is terminated. +.SH ERRORS +These functions may fail if: +.TP +.BR EINTR +A signal was caught during the operation. +.TP +.BR EIO +An I/O error has occurred. +.P +In addition, +\fIgetpwent\fR() +and +\fIsetpwent\fR() +may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Searching the User Database" +.P +The following example uses the +\fIgetpwent\fR() +function to get successive entries in the user database, returning a +pointer to a +.BR passwd +structure that contains information about each user. The call to +\fIendpwent\fR() +closes the user database and cleans up. +.sp +.RS 4 +.nf + +#include +#include +.P +void printname(uid_t uid) +{ + struct passwd *pwd; +.P + setpwent(); + while((pwd = getpwent()) != NULL) { + if (pwd->pw_uid == uid) { + printf("name=%s\en",pwd->pw_name); + break; + } + } + endpwent(); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +These functions are provided due to their historical usage. +Applications should avoid dependencies on fields in the password +database, whether the database is a single file, or where in the +file system name space the database resides. Applications should use +\fIgetpwuid\fR() +whenever possible because it avoids these dependencies. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)", +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/endservent.3p b/upstream/archlinux/man3p/endservent.3p new file mode 100644 index 00000000..901ff8c2 --- /dev/null +++ b/upstream/archlinux/man3p/endservent.3p @@ -0,0 +1,173 @@ +'\" et +.TH ENDSERVENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +endservent, +getservbyname, +getservbyport, +getservent, +setservent +\(em network services database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endservent(void); +struct servent *getservbyname(const char *\fIname\fP, const char *\fIproto\fP); +struct servent *getservbyport(int \fIport\fP, const char *\fIproto\fP); +struct servent *getservent(void); +void setservent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +These functions shall retrieve information about network services. This +information is considered to be stored in a database that can be +accessed sequentially or randomly. The implementation of this database +is unspecified. +.P +The +\fIsetservent\fR() +function shall open a connection to the database, and set the next +entry to the first entry. If the +.IR stayopen +argument is non-zero, the +.IR net +database shall not be closed after each call to the +\fIgetservent\fR() +function (either directly, or indirectly through one of the other +.IR getserv* (\|) +functions), and the implementation may maintain an open file descriptor +for the database. +.P +The +\fIgetservent\fR() +function shall read the next entry of the database, opening and closing +a connection to the database as necessary. +.P +The +\fIgetservbyname\fR() +function shall search the database from the beginning and find the +first entry for which the service name specified by +.IR name +matches the +.IR s_name +member and the protocol name specified by +.IR proto +matches the +.IR s_proto +member, opening and closing a connection to the database as necessary. +If +.IR proto +is a null pointer, any value of the +.IR s_proto +member shall be matched. +.P +The +\fIgetservbyport\fR() +function shall search the database from the beginning and find the +first entry for which the port specified by +.IR port +matches the +.IR s_port +member and the protocol name specified by +.IR proto +matches the +.IR s_proto +member, opening and closing a connection to the database as necessary. +If +.IR proto +is a null pointer, any value of the +.IR s_proto +member shall be matched. The +.IR port +argument shall be a value obtained by converting a +.BR uint16_t +in network byte order to +.BR int . +.P +The +\fIgetservbyname\fR(), +\fIgetservbyport\fR(), +and +\fIgetservent\fR() +functions shall each return a pointer to a +.BR servent +structure, the members of which shall contain the fields of an entry in +the network services database. +.P +The +\fIendservent\fR() +function shall close the database, releasing any open file descriptor. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetservbyname\fR(), +\fIgetservbyport\fR(), +and +\fIgetservent\fR() +return a pointer to a +.BR servent +structure if the requested entry was found, and a null pointer if the +end of the database was reached or the requested entry was not found. +Otherwise, a null pointer is returned. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetservbyname\fR(), +\fIgetservbyport\fR(), +or +\fIgetservent\fR(). +The returned pointer, and pointers within the structure, might also be +invalidated if the calling thread is terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +.IR port +argument of +\fIgetservbyport\fR() +need not be compatible with the port values of all address families. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIhtonl\fR\^(\|)", +.IR "\fIinet_addr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/endutxent.3p b/upstream/archlinux/man3p/endutxent.3p new file mode 100644 index 00000000..1e944e4f --- /dev/null +++ b/upstream/archlinux/man3p/endutxent.3p @@ -0,0 +1,240 @@ +'\" et +.TH ENDUTXENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +endutxent, +getutxent, +getutxid, +getutxline, +pututxline, +setutxent +\(em user accounting database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void endutxent(void); +struct utmpx *getutxent(void); +struct utmpx *getutxid(const struct utmpx *\fIid\fP); +struct utmpx *getutxline(const struct utmpx *\fIline\fP); +struct utmpx *pututxline(const struct utmpx *\fIutmpx\fP); +void setutxent(void); +.fi +.SH DESCRIPTION +These functions shall provide access to the user accounting database. +.P +The +\fIgetutxent\fR() +function shall read the next entry from the user accounting database. +If the database is not already open, it shall open it. If it reaches +the end of the database, it shall fail. +.P +The +\fIgetutxid\fR() +function shall search forward from the current point in the database. +If the +.IR ut_type +value of the +.BR utmpx +structure pointed to by +.IR id +is BOOT_TIME, OLD_TIME, or NEW_TIME, then it shall stop when it finds +an +entry with a matching +.IR ut_type +value. If the +.IR ut_type +value is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, +or DEAD_PROCESS, then it shall stop when it finds an entry whose type +is one of these four and whose +.IR ut_id +member matches the +.IR ut_id +member of the +.BR utmpx +structure pointed to by +.IR id . +If the end of the database is reached without a match, +\fIgetutxid\fR() +shall fail. +.P +The +\fIgetutxline\fR() +function shall search forward from the current point in the database +until it finds an entry of the type LOGIN_PROCESS or USER_PROCESS which +also has a +.IR ut_line +value matching that in the +.BR utmpx +structure pointed to by +.IR line . +If the end of the database is reached without a match, +\fIgetutxline\fR() +shall fail. +.P +The +\fIgetutxid\fR() +or +\fIgetutxline\fR() +function may cache data. For this reason, to use +\fIgetutxline\fR() +to search for multiple occurrences, the application shall zero out the +static data after each success, or +\fIgetutxline\fR() +may return a pointer to the same +.BR utmpx +structure. +.P +There is one exception to the rule about clearing the structure before +further reads are done. The implicit read done by +\fIpututxline\fR() +(if it finds that it is not already at the correct place in the user +accounting database) shall not modify the static structure returned by +\fIgetutxent\fR(), +\fIgetutxid\fR(), +or +\fIgetutxline\fR(), +if the application has modified this structure and passed the +pointer back to +\fIpututxline\fR(). +.P +For all entries that match a request, the +.IR ut_type +member indicates the type of the entry. Other members of the entry +shall contain meaningful data based on the value of the +.IR ut_type +member as follows: +.TS +box center tab(!); +cB | cB +l | l. +ut_type Member!Other Members with Meaningful Data +_ +EMPTY!No others +BOOT_TIME!\fIut_tv\fP +OLD_TIME!\fIut_tv\fP +NEW_TIME!\fIut_tv\fP +USER_PROCESS!\fIut_id\fP, \fIut_user\fP (login name of the user), \fIut_line\fP, \fIut_pid\fP, \fIut_tv\fP +INIT_PROCESS!\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP +LOGIN_PROCESS!T{ +.IR ut_id , +.IR ut_user +(implementation-defined name of the login process), +.IR ut_line , +.IR ut_pid , +.IR ut_tv +T} +DEAD_PROCESS!\fIut_id\fP, \fIut_pid\fP, \fIut_tv\fP +.TE +.P +An implementation that provides extended security controls may impose +implementation-defined restrictions on accessing the user accounting +database. In particular, the system may deny the existence of some or +all of the user accounting database entries associated with users other +than the caller. +.P +If the process has appropriate privileges, the +\fIpututxline\fR() +function shall write out the structure into the user accounting +database. It shall search for a record as if by +\fIgetutxid\fR() +that satisfies the request. If this search succeeds, then the entry +shall be replaced. Otherwise, a new entry shall be made at the end of +the user accounting database. +.P +The +\fIendutxent\fR() +function shall close the user accounting database. +.P +The +\fIsetutxent\fR() +function shall reset the input to the beginning of the database. This +should be done before each search for a new entry if it is desired that +the entire database be examined. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetutxent\fR(), +\fIgetutxid\fR(), +and +\fIgetutxline\fR() +shall return a pointer to a +.BR utmpx +structure containing a copy of the requested entry in the user +accounting database. Otherwise, a null pointer shall be returned. +.P +The return value may point to a static area which is overwritten by a +subsequent call to +\fIgetutxid\fR() +or +\fIgetutxline\fR(). +.P +Upon successful completion, +\fIpututxline\fR() +shall return a pointer to a +.BR utmpx +structure containing a copy of the entry added to the user accounting +database. Otherwise, a null pointer shall be returned. +.P +The +\fIendutxent\fR() +and +\fIsetutxent\fR() +functions shall not return a value. +.SH ERRORS +No errors are defined for the +\fIendutxent\fR(), +\fIgetutxent\fR(), +\fIgetutxid\fR(), +\fIgetutxline\fR(), +and +\fIsetutxent\fR() +functions. +.P +The +\fIpututxline\fR() +function may fail if: +.TP +.BR EPERM +The process does not have appropriate privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The sizes of the arrays in the structure can be found using the +.IR sizeof +operator. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/environ.3p b/upstream/archlinux/man3p/environ.3p new file mode 100644 index 00000000..d745673e --- /dev/null +++ b/upstream/archlinux/man3p/environ.3p @@ -0,0 +1,40 @@ +'\" et +.TH ENVIRON "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +environ +\(em array of character pointers to the environment strings +.SH SYNOPSIS +.LP +.nf +extern char **environ; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIexec\fR\^" +and the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/erand48.3p b/upstream/archlinux/man3p/erand48.3p new file mode 100644 index 00000000..6b0d5bf5 --- /dev/null +++ b/upstream/archlinux/man3p/erand48.3p @@ -0,0 +1,40 @@ +'\" et +.TH ERAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +erand48 +\(em generate uniformly distributed pseudo-random numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double erand48(unsigned short \fIxsubi\fP[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/erf.3p b/upstream/archlinux/man3p/erf.3p new file mode 100644 index 00000000..67214e29 --- /dev/null +++ b/upstream/archlinux/man3p/erf.3p @@ -0,0 +1,153 @@ +'\" et +.TH ERF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.EQ +delim $$ +.EN +.SH NAME +erf, +erff, +erfl +\(em error functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double erf(double \fIx\fP); +float erff(float \fIx\fP); +long double erfl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the error function of their argument +.IR x , +defined as: +.sp +.RS +${2 over sqrt pi} int from 0 to x e"^" " "{- t"^" 2" "} dt$ +.RE +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the value of +the error function. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, \(+-0 shall be returned. +.P +If +.IR x +is \(+-Inf, \(+-1 shall be returned. +.P +If the correct value would cause underflow, a range error may occur, and +\fIerf\fR(), +\fIerff\fR(), +and +\fIerfl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If the IEC 60559 Floating-Point option is supported, 2 * +.IR x /\c +.IR sqrt (\(*p) +should be returned. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.br +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Computing the Probability for a Normal Variate" +.P +This example shows how to use +\fIerf\fR() +to compute the probability that a normal variate assumes a value in the +range [\fIx\fR1,\fIx\fR2] with \fIx\fR1\(<=\fIx\fR2. +.P +This example uses the constant M_SQRT1_2 which is part of the XSI option. +.sp +.RS 4 +.nf + +#include +.P +double +Phi(const double x1, const double x2) +{ + return ( erf(x2*M_SQRT1_2) - erf(x1*M_SQRT1_2) ) / 2; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +Underflow occurs when |\fIx\fP| < DBL_MIN * (\c +.IR sqrt (\(*p)/2). +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIerfc\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/erfc.3p b/upstream/archlinux/man3p/erfc.3p new file mode 100644 index 00000000..c5dc76db --- /dev/null +++ b/upstream/archlinux/man3p/erfc.3p @@ -0,0 +1,136 @@ +'\" et +.TH ERFC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +erfc, +erfcf, +erfcl +\(em complementary error functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double erfc(double \fIx\fP); +float erfcf(float \fIx\fP); +long double erfcl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the complementary error function 1.0 \- +.IR erf ( x ). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the value of +the complementary error function. +.P +If the correct value would cause underflow, +and is not +representable, +a range error may occur, and +\fIerfc\fR(), +\fIerfcf\fR(), +and +\fIerfcl\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +1 shall be returned. +.P +If +.IR x +is \-Inf, +2 shall be returned. +.P +If +.IR x +is +Inf, +0 shall be returned. +.P +If the correct value would cause underflow and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIerfc\fR() +function is provided because of the extreme loss of relative accuracy if +.IR erf ( x ) +is called for large +.IR x +and the result subtracted from 1.0. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIerf\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/erff.3p b/upstream/archlinux/man3p/erff.3p new file mode 100644 index 00000000..942f26a6 --- /dev/null +++ b/upstream/archlinux/man3p/erff.3p @@ -0,0 +1,42 @@ +'\" et +.TH ERFF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +erff, +erfl +\(em error functions +.SH SYNOPSIS +.LP +.nf +#include +.P +float erff(float \fIx\fP); +long double erfl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIerf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/errno.3p b/upstream/archlinux/man3p/errno.3p new file mode 100644 index 00000000..41c2ab7f --- /dev/null +++ b/upstream/archlinux/man3p/errno.3p @@ -0,0 +1,108 @@ +'\" et +.TH ERRNO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +errno +\(em error return value +.SH SYNOPSIS +.LP +.nf +#include +.fi +.SH DESCRIPTION +The lvalue +.IR errno +is used by many functions to return error values. +.P +Many functions provide an error number in +.IR errno , +which has type +.BR int +and is defined in +.IR . +The value of +.IR errno +shall be defined only after a call to a function for which it is +explicitly stated to be set and until it is changed by the next +function call or if the application assigns it a value. The value of +.IR errno +should only be examined when it is indicated to be valid by a +function's return value. Applications shall obtain the definition of +.IR errno +by the inclusion of +.IR . +No function in this volume of POSIX.1\(hy2017 shall set +.IR errno +to 0. The setting of +.IR errno +after a successful call to a function is unspecified unless the +description of that function specifies that +.IR errno +shall not be modified. +.P +It is unspecified whether +.IR errno +is a macro or an identifier declared with external linkage. If a macro +definition is suppressed in order to access an actual object, or a +program defines an identifier with the name +.IR errno , +the behavior is undefined. +.P +The symbolic values stored in +.IR errno +are documented in the ERRORS sections on all relevant pages. +.SH "RETURN VALUE" +None. +.SH ERRORS +None. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Previously both POSIX and X/Open documents were more restrictive than +the ISO\ C standard in that they required +.IR errno +to be defined as an external variable, whereas the ISO\ C standard required only +that +.IR errno +be defined as a modifiable lvalue with type +.BR int . +.P +An application that needs to examine the value of +.IR errno +to determine the error should set it to 0 before a function call, then +inspect it before a subsequent function call. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.3" ", " "Error Numbers" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/exec.3p b/upstream/archlinux/man3p/exec.3p new file mode 100644 index 00000000..552724a3 --- /dev/null +++ b/upstream/archlinux/man3p/exec.3p @@ -0,0 +1,1357 @@ +'\" et +.TH EXEC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +environ, +execl, +execle, +execlp, +execv, +execve, +execvp, +fexecve +\(em execute a file +.SH SYNOPSIS +.LP +.nf +#include +.P +extern char **environ; +int execl(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*, (char *)0 */); +int execle(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*, + (char *)0, char *const \fIenvp\fP[]*/); +int execlp(const char *\fIfile\fP, const char *\fIarg0\fP, ... /*, (char *)0 */); +int execv(const char *\fIpath\fP, char *const \fIargv\fP[]); +int execve(const char *\fIpath\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); +int execvp(const char *\fIfile\fP, char *const \fIargv\fP[]); +int fexecve(int \fIfd\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]); +.fi +.SH DESCRIPTION +The +.IR exec +family of functions shall replace the current process image with a new +process image. The new image shall be constructed from a regular, +executable file called the +.IR "new process image file" . +There shall be no return from a successful +.IR exec , +because the calling process image is overlaid by the new process +image. +.P +The +\fIfexecve\fR() +function shall be equivalent to the +\fIexecve\fR() +function except that the file to be executed is determined by the file +descriptor +.IR fd +instead of a pathname. The file offset of +.IR fd +is ignored. +.P +When a C-language program is executed as a result of a call to one +of the +.IR exec +family of functions, it shall be entered as a C-language function call +as follows: +.sp +.RS 4 +.nf + +int main (\fIint argc, char *argv\fP[]); +.fi +.P +.RE +.P +where +.IR argc +is the argument count and +.IR argv +is an array of character pointers to the arguments themselves. +In addition, the following variable, which must be declared by the user +if it is to be used directly: +.sp +.RS 4 +.nf + +extern char **environ; +.fi +.P +.RE +.P +is initialized as a pointer to an array of character pointers to the +environment strings. The +.IR argv +and +.IR environ +arrays are each terminated by a null pointer. The null pointer +terminating the +.IR argv +array is not counted in +.IR argc . +.P +Applications can change the entire environment in a single operation by +assigning the +.IR environ +variable to point to an array of character pointers to the new environment +strings. After assigning a new value to +.IR environ , +applications should not rely on the new environment strings remaining +part of the environment, as a call to +\fIgetenv\fR(), +\fIputenv\fR(), +\fIsetenv\fR(), +\fIunsetenv\fR(), +or any function that is dependent on an environment variable may, on +noticing that +.IR environ +has changed, copy the environment strings to a new array and assign +.IR environ +to point to it. +.P +Any application that directly modifies the pointers to which the +.IR environ +variable points has undefined behavior. +.P +Conforming multi-threaded applications shall not use the +.IR environ +variable to access or modify any environment variable while any other +thread is concurrently modifying any environment variable. A call to +any function dependent on any environment variable shall be considered +a use of the +.IR environ +variable to access that environment variable. +.P +The arguments specified by a program with one of the +.IR exec +functions shall be passed on to the new process image in the +corresponding +\fImain\fR() +arguments. +.P +The argument +.IR path +points to a pathname that identifies the new process image file. +.P +The argument +.IR file +is used to construct a pathname that identifies the new process image +file. If the +.IR file +argument contains a + +character, the +.IR file +argument shall be used as the pathname for this file. Otherwise, the +path prefix for this file is obtained by a search of the directories +passed as the environment variable +.IR PATH +(see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables"). +If this environment variable is not present, the results +of the search are implementation-defined. +.P +There are two distinct ways in which the contents of the process image +file may cause the execution to fail, distinguished by the setting of +.IR errno +to either +.BR [ENOEXEC] +or +.BR [EINVAL] +(see the ERRORS section). In the cases where the other members of the +.IR exec +family of functions would fail and set +.IR errno +to +.BR [ENOEXEC] , +the +\fIexeclp\fR() +and +\fIexecvp\fR() +functions shall execute a command interpreter and the environment of the +executed command shall be as if the process invoked the +.IR sh +utility using +\fIexecl\fR() +as follows: +.sp +.RS 4 +.nf + +execl(, arg0, file, arg1, ..., (char *)0); +.fi +.P +.RE +.P +where <\fIshell\ path\fP> is an unspecified pathname for the +.IR sh +utility, +.IR file +is the process image file, and for +\fIexecvp\fR(), +where +.IR arg 0, +.IR arg 1, +and so on correspond to the values passed to +\fIexecvp\fR() +in +.IR argv [0], +.IR argv [1], +and so on. +.P +The arguments represented by +.IR arg0 ,\|.\|.\|. +are pointers to null-terminated character strings. These strings +shall constitute the argument list available to the new process +image. The list is terminated by a null pointer. The argument +.IR arg0 +should point to a filename string that is associated with the process +being started by one of the +.IR exec +functions. +.P +The argument +.IR argv +is an array of character pointers to null-terminated strings. The +application shall ensure that the last member of this array is a null +pointer. These strings shall constitute the argument list available to +the new process image. The value in +.IR argv [0] +should point to a filename string that is associated with the process +being started by one of the +.IR exec +functions. +.P +The argument +.IR envp +is an array of character pointers to null-terminated strings. These +strings shall constitute the environment for the new process image. +The +.IR envp +array is terminated by a null pointer. +.P +For those forms not containing an +.IR envp +pointer (\c +\fIexecl\fR(), +\fIexecv\fR(), +\fIexeclp\fR(), +and +\fIexecvp\fR()), +the environment for the new process image shall be taken from the +external variable +.IR environ +in the calling process. +.P +The number of bytes available for the new process' combined argument +and environment lists is +{ARG_MAX}. +It is implementation-defined whether null terminators, pointers, +and/or any alignment bytes are included in this total. +.P +File descriptors open in the calling process image shall remain open in +the new process image, except for those whose close-on-\c +.IR exec +flag FD_CLOEXEC is set. +For those file descriptors that remain open, all attributes of the open +file description remain unchanged. For any file descriptor that is +closed for this reason, file locks are removed as a result of the close +as described in +\fIclose\fR(). +Locks that are not removed by closing of file descriptors remain +unchanged. +.P +If file descriptor 0, 1, or 2 would otherwise be closed after a successful +call to one of the +.IR exec +family of functions, implementations may open an unspecified file for +the file descriptor in the new process image. If a standard utility +or a conforming application is executed with file descriptor 0 not +open for reading or with file descriptor 1 or 2 not open for writing, +the environment in which the utility or application is executed shall +be deemed non-conforming, and consequently the utility or application +might not behave as described in this standard. +.P +Directory streams open in the calling process image shall be closed +in the new process image. +.P +The state of the floating-point environment in the initial thread +of the new process image shall be set to the default. +.P +The state of conversion descriptors +and message catalog descriptors in the new process image is undefined. +.P +For the new process image, the equivalent of: +.sp +.RS 4 +.nf + +setlocale(LC_ALL, "C") +.fi +.P +.RE +.P +shall be executed at start-up. +.P +Signals set to the default action (SIG_DFL) in the calling process +image shall be set to the default action in the new process image. +Except for SIGCHLD, signals set to be ignored (SIG_IGN) by the calling +process image shall be set to be +ignored by the new process image. Signals set to be caught by the +calling process image shall be set to the default action in the new +process image (see +.IR ). +.P +If the SIGCHLD signal is set to be ignored by the calling process +image, it is unspecified whether the SIGCHLD signal is set to be +ignored or to the default action in the new process image. +.P +After a successful call to any of the +.IR exec +functions, alternate signal stacks are not preserved and the SA_ONSTACK +flag +shall be cleared for all signals. +.P +After a successful call to any of the +.IR exec +functions, any functions previously registered by the +\fIatexit\fR() +or +\fIpthread_atfork\fR() +functions are no longer registered. +.P +If the ST_NOSUID bit is set for the file system containing the new +process +image file, then the effective user ID, effective group ID, saved +set-user-ID, and saved set-group-ID are unchanged in the new process +image. Otherwise, +if the set-user-ID mode bit of the new process image file is set, the +effective user ID of the new process image shall be set to the user ID +of the new process image file. Similarly, if the set-group-ID mode bit +of the new process image file is set, the effective group ID of the new +process image shall be set to the group ID of the new process image +file. The real user ID, real group ID, and supplementary group IDs of +the new process image shall remain the same as those of the calling +process image. The effective user ID and effective group ID of the new +process image shall be saved (as the saved set-user-ID and the saved +set-group-ID) for use by +\fIsetuid\fR(). +.P +Any shared memory segments attached to the calling process image +shall not be attached to the new process image. +.P +Any named semaphores open in the calling process shall be closed as +if by appropriate calls to +\fIsem_close\fR(). +.P +Any blocks of typed memory that were mapped in the calling process are +unmapped, as if +\fImunmap\fR() +was implicitly called to unmap them. +.P +Memory locks established by the calling process via calls to +\fImlockall\fR() +or +\fImlock\fR() +shall be removed. If locked pages in the address space of the calling +process are also mapped into the address spaces of other processes and +are locked by those processes, the locks established by the other +processes shall be unaffected by the call by this process to the +.IR exec +function. If the +.IR exec +function fails, the effect on memory locks is unspecified. +.P +Memory mappings created in the process are unmapped before the address +space is rebuilt for the new process image. +.P +When the calling process image does not use the SCHED_FIFO, SCHED_RR, +or SCHED_SPORADIC +scheduling policies, the scheduling policy and parameters of the +new process image and the initial thread in that new process image are +implementation-defined. +.P +When the calling process image uses the SCHED_FIFO, SCHED_RR, or +SCHED_SPORADIC scheduling policies, the process policy and scheduling +parameter settings shall not be changed by a call to an +.IR exec +function. +The initial thread in the new process image shall inherit the +process scheduling policy and parameters. It shall have the default +system contention scope, but shall inherit its allocation domain +from the calling process image. +.P +Per-process timers created by the calling process shall be deleted before +replacing the current process image with the new process image. +.P +All open message queue descriptors in the calling process shall be closed, +as described in +\fImq_close\fR(). +.P +Any outstanding asynchronous I/O operations may be canceled. Those +asynchronous I/O operations that are not canceled shall complete as if +the +.IR exec +function had not yet occurred, but any associated signal notifications +shall be suppressed. It is unspecified whether the +.IR exec +function itself blocks awaiting such I/O completion. In no event, +however, shall the new process image created by the +.IR exec +function be affected by the presence of outstanding asynchronous I/O +operations at the time the +.IR exec +function is called. Whether any I/O is canceled, and which I/O may be +canceled upon +.IR exec , +is implementation-defined. +.P +The new process image shall inherit the CPU-time clock of the calling +process image. This inheritance means that the process CPU-time clock +of the process being +.IR exec -ed +shall not be reinitialized or altered as a result of the +.IR exec +function other than to reflect the time spent by the process executing +the +.IR exec +function itself. +.P +The initial value of the CPU-time clock of the initial thread of the +new process image shall be set to zero. +.P +If the calling process is being traced, the new process image shall +continue to be traced into the same trace stream as the original +process image, but the new process image shall not inherit the mapping +of trace event names to trace event type identifiers that was defined +by calls to the +\fIposix_trace_eventid_open\fR() +or the +\fIposix_trace_trid_eventid_open\fR() +functions in the calling process image. +.P +If the calling process is a trace controller process, any trace streams +that were created by the calling process shall be shut down as +described in the +\fIposix_trace_shutdown\fR() +function. +.P +The thread ID of the initial thread in the new process image is +unspecified. +.P +The size and location of the stack on which the initial thread in the +new process image runs is unspecified. +.P +The initial thread in the new process image shall have its cancellation +type set to PTHREAD_CANCEL_DEFERRED and its cancellation state set to +PTHREAD_CANCEL_ENABLED. +.P +The initial thread in the new process image shall have all +thread-specific data values set to NULL and all thread-specific data +keys shall be removed by the call to +.IR exec +without running destructors. +.P +The initial thread in the new process image shall be joinable, as if +created with the +.IR detachstate +attribute set to PTHREAD_CREATE_JOINABLE. +.P +The new process shall inherit at least the following attributes from +the calling process image: +.IP " *" 4 +Nice value (see +\fInice\fR()) +.IP " *" 4 +\fIsemadj\fP values (see +\fIsemop\fR()) +.IP " *" 4 +Process ID +.IP " *" 4 +Parent process ID +.IP " *" 4 +Process group ID +.IP " *" 4 +Session membership +.IP " *" 4 +Real user ID +.IP " *" 4 +Real group ID +.IP " *" 4 +Supplementary group IDs +.IP " *" 4 +Time left until an alarm clock signal (see +\fIalarm\fR()) +.IP " *" 4 +Current working directory +.IP " *" 4 +Root directory +.IP " *" 4 +File mode creation mask (see +\fIumask\fR()) +.IP " *" 4 +File size limit (see +\fIgetrlimit\fR() +and +\fIsetrlimit\fR()) +.IP " *" 4 +Process signal mask (see +\fIpthread_sigmask\fR()) +.IP " *" 4 +Pending signal (see +\fIsigpending\fR()) +.IP " *" 4 +.IR tms_utime , +.IR tms_stime , +.IR tms_cutime , +and +.IR tms_cstime +(see +\fItimes\fR()) +.IP " *" 4 +Resource limits +.IP " *" 4 +Controlling terminal +.IP " *" 4 +Interval timers +.P +The initial thread of the new process shall inherit at least the +following attributes from the calling thread: +.IP " *" 4 +Signal mask (see +\fIsigprocmask\fR() +and +\fIpthread_sigmask\fR()) +.IP " *" 4 +Pending signals (see +\fIsigpending\fR()) +.P +All other process attributes defined in this volume of POSIX.1\(hy2017 shall be inherited in the +new process image from the old process image. All other thread +attributes defined in this volume of POSIX.1\(hy2017 shall be inherited in the initial thread in +the new process image from the calling thread in the old process image. +The inheritance of process or thread attributes not defined by this volume of POSIX.1\(hy2017 is +implementation-defined. +.P +A call to any +.IR exec +function from a process with more than one thread shall result in all +threads being terminated and the new executable image being loaded and +executed. No destructor functions or cleanup handlers shall be called. +.P +Upon successful completion, the +.IR exec +functions shall mark for update the last data access timestamp +of the file. If an +.IR exec +function failed but was able to locate the process image file, whether the +last data access timestamp is marked for update is unspecified. Should the +.IR exec +function succeed, the process image file shall be considered to have been +opened with +\fIopen\fR(). +The corresponding +\fIclose\fR() +shall be considered to occur at a time after this open, but before process +termination or successful completion of a subsequent call to one of the +.IR exec +functions, +\fIposix_spawn\fR(), +or +\fIposix_spawnp\fR(). +The +.IR argv [\|] +and +.IR envp [\|] +arrays of pointers and the strings to which those arrays point shall +not be modified by a call to one of the +.IR exec +functions, except as a consequence of replacing the process image. +.P +The saved resource limits in the new process image are set to be a copy +of the process' corresponding hard and soft limits. +.SH "RETURN VALUE" +If one of the +.IR exec +functions returns to the calling process image, an error has occurred; +the return value shall be \-1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +.IR exec +functions shall fail if: +.TP +.BR E2BIG +The number of bytes used by the new process image's argument list and +environment list is greater than the system-imposed limit of +{ARG_MAX} +bytes. +.TP +.BR EACCES +The new process image file is not a regular file and the implementation +does not support execution of files of its type. +.TP +.BR EINVAL +The new process image file has appropriate privileges and has a +recognized executable binary format, but the system does not support +execution of a file with this format. +.P +The +.IR exec +functions, except for +\fIfexecve\fR(), +shall fail if: +.TP +.BR EACCES +Search permission is denied for a directory listed in the new process +image file's path prefix, or the new process image file denies execution +permission. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +or +.IR file +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +or +.IR file +does not name an existing file or +.IR path +or +.IR file +is an empty string. +.TP +.BR ENOTDIR +A component of the new process image file's path prefix names an existing +file that is neither a directory nor a symbolic link to a directory, +or the new process image file's pathname contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.P +The +.IR exec +functions, except for +\fIexeclp\fR() +and +\fIexecvp\fR(), +shall fail if: +.TP +.BR ENOEXEC +The new process image file has the appropriate access permission but +has an unrecognized format. +.P +The +\fIfexecve\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor open for executing. +.P +The +.IR exec +functions may fail if: +.TP +.BR ENOMEM +The new process image requires more memory than is allowed by +the hardware or system-imposed memory management constraints. +.P +The +.IR exec +functions, except for +\fIfexecve\fR(), +may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +or +.IR file +argument. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR path +argument or the length of the pathname constructed from the +.IR file +argument exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate result +with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The new process image file is a pure procedure (shared text) file that +is currently open for writing by some process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using execl(\|)" +.P +The following example executes the +.IR ls +command, specifying the pathname of the executable (\c +.BR /bin/ls ) +and using arguments supplied directly to the command to produce +single-column output. +.sp +.RS 4 +.nf + +#include +.P +int ret; +\&... +ret = execl ("/bin/ls", "ls", "-1", (char *)0); +.fi +.P +.RE +.SS "Using execle(\|)" +.P +The following example is similar to +.IR "Using execl(\|)". +In addition, it specifies the environment for the new process image +using the +.IR env +argument. +.sp +.RS 4 +.nf + +#include +.P +int ret; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execle ("/bin/ls", "ls", "-l", (char *)0, env); +.fi +.P +.RE +.SS "Using execlp(\|)" +.P +The following example searches for the location of the +.IR ls +command among the directories specified by the +.IR PATH +environment variable. +.sp +.RS 4 +.nf + +#include +.P +int ret; +\&... +ret = execlp ("ls", "ls", "-l", (char *)0); +.fi +.P +.RE +.SS "Using execv(\|)" +.P +The following example passes arguments to the +.IR ls +command in the +.IR cmd +array. +.sp +.RS 4 +.nf + +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execv ("/bin/ls", cmd); +.fi +.P +.RE +.SS "Using execve(\|)" +.P +The following example passes arguments to the +.IR ls +command in the +.IR cmd +array, and specifies the environment for the new process image using the +.IR env +argument. +.sp +.RS 4 +.nf + +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 }; +\&... +ret = execve ("/bin/ls", cmd, env); +.fi +.P +.RE +.SS "Using execvp(\|)" +.P +The following example searches for the location of the +.IR ls +command among the directories specified by the +.IR PATH +environment variable, and passes arguments to the +.IR ls +command in the +.IR cmd +array. +.sp +.RS 4 +.nf + +#include +.P +int ret; +char *cmd[] = { "ls", "-l", (char *)0 }; +\&... +ret = execvp ("ls", cmd); +.fi +.P +.RE +.SH "APPLICATION USAGE" +As the state of conversion descriptors and message catalog +descriptors in the new process image is undefined, conforming +applications should not rely on their use and should close them prior +to calling one of the +.IR exec +functions. +.P +Applications that require other than the default POSIX locale as the +global locale in the new process image should call +\fIsetlocale\fR() +with the appropriate parameters. +.P +When assigning a new value to the +.IR environ +variable, applications should ensure that the environment to which it +will point contains at least the following: +.IP " 1." 4 +Any implementation-defined variables required by the implementation to +provide a conforming environment. See the _CS_V7_ENV entry in +.IR +and +\fIconfstr\fR() +for details. +.IP " 2." 4 +A value for +.IR PATH +which finds conforming versions of all standard utilities before any +other versions. +.P +The same constraint applies to the +.IR envp +array passed to +\fIexecle\fR() +or +\fIexecve\fR(), +in order to ensure that the new process image is invoked in a conforming +environment. +.P +Applications should not execute programs with file descriptor 0 not open +for reading or with file descriptor 1 or 2 not open for writing, as this +might cause the executed program to misbehave. In order not to pass on +these file descriptors to an executed program, applications should not +just close them but should reopen them on, for example, +.BR /dev/null . +Some implementations may reopen them automatically, but applications +should not rely on this being done. +.P +If an application wants to perform a checksum test of the file being +executed before executing it, the file will need to be opened with read +permission to perform the checksum test. +.P +Since execute permission is checked by +\fIfexecve\fR(), +the file description +.IR fd +need not have been opened with the O_EXEC flag. However, if the file +to be executed denies read and write permission for the process +preparing to do the +.IR exec , +the only way to provide the +.IR fd +to +\fIfexecve\fR() +will be to use the O_EXEC flag when opening +.IR fd . +In this case, the application will not be able to perform a checksum +test since it will not be able to read the contents of the file. +.P +Note that when a file descriptor is opened with O_RDONLY, O_RDWR, or +O_WRONLY mode, the file descriptor can be used to read, read and write, +or write the file, respectively, even if the mode of the file changes +after the file was opened. Using the O_EXEC open mode is different; +\fIfexecve\fR() +will ignore the mode that was used when the file descriptor was opened +and the +.IR exec +will fail if the mode of the file associated with +.IR fd +does not grant execute permission to the calling process at the time +\fIfexecve\fR() +is called. +.SH RATIONALE +Early proposals required that the value of +.IR argc +passed to +\fImain\fR() +be ``one or greater''. This was driven by the same requirement in +drafts of the ISO\ C standard. +In fact, historical implementations have passed a value of zero when no +arguments are supplied to the caller of the +.IR exec +functions. This requirement was removed from the ISO\ C standard and subsequently +removed from this volume of POSIX.1\(hy2017 as well. The wording, in particular the use of the +word \fIshould\fP, requires a Strictly Conforming POSIX Application +to pass at least one argument to the +.IR exec +function, thus guaranteeing that +.IR argc +be one or greater when invoked by such an application. In fact, this is +good practice, since many existing applications reference +.IR argv [0] +without first checking the value of +.IR argc . +.P +The requirement on a Strictly Conforming POSIX Application also states +that the value passed as the first argument be a filename string +associated with the process being started. Although some existing +applications pass a pathname rather than a filename string in some +circumstances, a filename string is more generally useful, since the +common usage of +.IR argv [0] +is in printing diagnostics. In some cases the filename passed is not +the actual filename of the file; for example, many implementations of the +.IR login +utility use a convention of prefixing a + +(\c +.BR '\(hy' ) +to the actual filename, which indicates to the command interpreter being +invoked that it is a ``login shell''. +.P +Also, note that the +.IR test +and +.IR [ +utilities require specific strings for the +.IR argv [0] +argument to have deterministic behavior across all implementations. +.P +Historically, there have been two ways that implementations can +.IR exec +shell scripts. +.P +One common historical implementation is that the +\fIexecl\fR(), +\fIexecv\fR(), +\fIexecle\fR(), +and +\fIexecve\fR() +functions return an +.BR [ENOEXEC] +error for any file not recognizable as executable, including a shell +script. When the +\fIexeclp\fR() +and +\fIexecvp\fR() +functions encounter such a file, they assume the file to be a shell +script and invoke a known command interpreter to interpret such files. +This is now required by POSIX.1\(hy2008. These implementations of +\fIexecvp\fR() +and +\fIexeclp\fR() +only give the +.BR [ENOEXEC] +error in the rare case of a problem with the command interpreter's +executable file. Because of these implementations, the +.BR [ENOEXEC] +error is not mentioned for +\fIexeclp\fR() +or +\fIexecvp\fR(), +although implementations can still give it. +.P +Another way that some historical implementations handle shell scripts +is by recognizing the first two bytes of the file as the character +string +.BR \(dq#!\(dq +and using the remainder of the first line of the file as the name of +the command interpreter to execute. +.P +One potential source of confusion noted by the standard developers +is over how the contents of a process image file affect the behavior +of the +.IR exec +family of functions. The following is a description of the actions +taken: +.IP " 1." 4 +If the process image file is a valid executable (in a format that is +executable and valid and having appropriate privileges) for this +system, then the system executes the file. +.IP " 2." 4 +If the process image file has appropriate privileges and is in a format +that is executable but not valid for this system (such as a recognized +binary for another architecture), then this is an error and +.IR errno +is set to +.BR [EINVAL] +(see later RATIONALE on +.BR [EINVAL] ). +.IP " 3." 4 +If the process image file has appropriate privileges but is not +otherwise recognized: +.RS 4 +.IP " a." 4 +If this is a call to +\fIexeclp\fR() +or +\fIexecvp\fR(), +then they invoke a command interpreter assuming that the process image +file is a shell script. +.IP " b." 4 +If this is not a call to +\fIexeclp\fR() +or +\fIexecvp\fR(), +then an error occurs and +.IR errno +is set to +.BR [ENOEXEC] . +.RE +.P +Applications that do not require to access their arguments may use +the form: +.sp +.RS 4 +.nf + +main(void) +.fi +.P +.RE +as specified in the ISO\ C standard. However, the implementation will always +provide the two arguments +.IR argc +and +.IR argv , +even if they are not used. +.P +Some implementations provide a third argument to +\fImain\fR() +called +.IR envp . +This is defined as a pointer to the environment. The ISO\ C standard +specifies invoking +\fImain\fR() +with two arguments, so implementations must support applications +written this way. Since this volume of POSIX.1\(hy2017 defines the global variable +.IR environ , +which is also provided by historical implementations and can be used +anywhere that +.IR envp +could be used, there is no functional need for the +.IR envp +argument. Applications should use the +\fIgetenv\fR() +function rather than accessing the environment directly via either +.IR envp +or +.IR environ . +Implementations are required to support the two-argument calling +sequence, but this does not prohibit an implementation from supporting +.IR envp +as an optional third argument. +.P +This volume of POSIX.1\(hy2017 specifies that signals set to SIG_IGN +remain set to SIG_IGN, and that the new process image inherits the +signal mask of the thread that called +.IR exec +in the old process image. This is consistent with historical +implementations, and it permits some useful functionality, such as the +.IR nohup +command. However, it should be noted that many existing applications +wrongly assume that they start with certain signals set to the default +action and/or unblocked. In particular, applications written with a +simpler signal model that does not include blocking of signals, such as +the one in the ISO\ C standard, may not behave properly if invoked with some +signals blocked. Therefore, it is best not to block or ignore signals +across +.IR exec s +without explicit reason to do so, and especially not to block signals +across +.IR exec s +of arbitrary (not closely cooperating) programs. +.P +The +.IR exec +functions always save the value of the effective user ID +and effective group ID +of the process at the completion of the +.IR exec , +whether or not the set-user-ID +or the set-group-ID +bit of the process image file is set. +.P +The statement about +.IR argv [\|] +and +.IR envp [\|] +being constants is included to make explicit to future writers of +language bindings that these objects are completely constant. Due to a +limitation of the ISO\ C standard, it is not possible to state that idea in +standard C. Specifying two levels of +.IR const \-\c +.IR qualification +for the +.IR argv [\|] +and +.IR envp [\|] +parameters for the +.IR exec +functions may seem to be the natural choice, given that these functions +do not modify either the array of pointers or the characters to which +the function points, but this would disallow existing correct code. +Instead, only the array of pointers is noted as constant. The table of +assignment compatibility for +.IR dst =\c +.IR src +derived from the ISO\ C standard summarizes the compatibility: +.TS +box tab(!) center; +r | lB | lB | lB | lB +lB | c | c | c | c. +\fIdst\fP:!char *[\|]!const char *[\|]!char *const[\|]!const char *const[\|] +_ +\fIsrc\fP: +char *[\|]!VALID!\(em!VALID!\(em +const char *[\|]!\(em!VALID!\(em!VALID +char * const [\|]!\(em!\(em!VALID!\(em +const char *const[\|]!\(em!\(em!\(em!VALID +.TE +.P +Since all existing code has a source type matching the first row, the +column that gives the most valid combinations is the third column. The +only other possibility is the fourth column, but using it would require +a cast on the +.IR argv +or +.IR envp +arguments. It is unfortunate that the fourth column cannot be used, +because the declaration a non-expert would naturally use would be that +in the second row. +.P +The ISO\ C standard and this volume of POSIX.1\(hy2017 do not conflict on the use of +.IR environ , +but some historical implementations of +.IR environ +may cause a conflict. As long as +.IR environ +is treated in the same way as an entry point (for example, +\fIfork\fR()), +it conforms to both standards. A library can contain +\fIfork\fR(), +but if there is a user-provided +\fIfork\fR(), +that +\fIfork\fR() +is given precedence and no problem ensues. The situation is similar +for +.IR environ : +the definition in this volume of POSIX.1\(hy2017 is to be used if there is no user-provided +.IR environ +to take precedence. At least three implementations are known to exist +that solve this problem. +.TP +.BR E2BIG +The limit +{ARG_MAX} +applies not just to the size of the argument list, but to the sum of +that and the size of the environment list. +.TP +.BR EFAULT +Some historical systems return +.BR [EFAULT] +rather than +.BR [ENOEXEC] +when the new process image file is corrupted. They are non-conforming. +.TP +.BR EINVAL +This error condition was added to POSIX.1\(hy2008 to allow an implementation to +detect executable files generated for different architectures, and +indicate this situation to the application. Historical implementations +of shells, +\fIexecvp\fR(), +and +\fIexeclp\fR() +that encounter an +.BR [ENOEXEC] +error will execute a shell on the assumption that the file is a shell +script. This will not produce the desired effect when the file is a +valid executable for a different architecture. An implementation may +now choose to avoid this problem by returning +.BR [EINVAL] +when a valid executable for a different architecture is encountered. +Some historical implementations return +.BR [EINVAL] +to indicate that the +.IR path +argument contains a character with the high order bit set. The +standard developers chose to deviate from historical practice for the +following reasons: +.RS 12 +.IP " 1." 4 +The new utilization of +.BR [EINVAL] +will provide some measure of utility to the user community. +.IP " 2." 4 +Historical use of +.BR [EINVAL] +is not acceptable in an internationalized operating environment. +.RE +.TP +.BR ENAMETOOLONG +.br +Since the file pathname may be constructed by taking elements in the +.IR PATH +variable and putting them together with the filename, the +.BR [ENAMETOOLONG] +error condition could also be reached this way. +.TP +.BR ETXTBSY +System V returns this error when the executable file is currently open +for writing by some process. This volume of POSIX.1\(hy2017 neither requires nor prohibits this +behavior. +.P +Other systems (such as System V) may return +.BR [EINTR] +from +.IR exec . +This is not addressed by this volume of POSIX.1\(hy2017, but implementations may have a +window between the call to +.IR exec +and the time that a signal could cause one of the +.IR exec +calls to return with +.BR [EINTR] . +.P +An explicit statement regarding the floating-point environment (as +defined in the +.IR +header) was added to make it clear that the floating-point environment +is set to its default when a call to one of the +.IR exec +functions succeeds. The requirements for inheritance or setting to the +default for other process and thread start-up functions is covered by +more generic statements in their descriptions and can be summarized as +follows: +.IP "\fIposix_spawn\fR\^(\|)" 14 +Set to default. +.IP "\fIfork\fR\^(\|)" 14 +Inherit. +.IP "\fIpthread_create\fR\^(\|)" 14 +Inherit. +.P +The purpose of the +\fIfexecve\fR() +function is to enable executing a file which has been verified to be +the intended file. It is possible to actively check the file by reading +from the file descriptor and be sure that the file is not exchanged for +another between the reading and the execution. Alternatively, a +function like +\fIopenat\fR() +can be used to open a file which has been found by reading the content +of a directory using +\fIreaddir\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIalarm\fR\^(\|)", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIfstatvfs\fR\^(\|)", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fInice\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fItest\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/exit.3p b/upstream/archlinux/man3p/exit.3p new file mode 100644 index 00000000..587c72b6 --- /dev/null +++ b/upstream/archlinux/man3p/exit.3p @@ -0,0 +1,113 @@ +'\" et +.TH EXIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +exit +\(em terminate a process +.SH SYNOPSIS +.LP +.nf +#include +.P +void exit(int \fIstatus\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The value of +.IR status +may be 0, EXIT_SUCCESS, EXIT_FAILURE, +or any other value, though only the least significant 8 bits (that is, +.IR status +& 0377) shall be available from +\fIwait\fR() +and +\fIwaitpid\fR(); +the full value shall be available from +\fIwaitid\fR() +and in the +.BR siginfo_t +passed to a signal handler for SIGCHLD. +.P +The +\fIexit\fR() +function shall first call all functions registered by +\fIatexit\fR(), +in the reverse order of their registration, except that a function is +called after any previously registered functions that had already been +called at the time it was registered. Each function is called as many +times as it was registered. If, during the call to any such function, a +call to the +\fIlongjmp\fR() +function is made that would terminate the call to the registered +function, the behavior is undefined. +.P +If a function registered by a call to +\fIatexit\fR() +fails to return, the remaining registered functions shall not be called +and the rest of the +\fIexit\fR() +processing shall not be completed. If +\fIexit\fR() +is called more than once, the behavior is undefined. +.P +The +\fIexit\fR() +function shall then flush all open streams with unwritten buffered data +and close all open streams. Finally, the process shall be terminated +with the same consequences as described in +.IR "Consequences of Process Termination". +.SH "RETURN VALUE" +The +\fIexit\fR() +function does not return. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See +\fI_Exit\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fI_Exit\fR\^(\|)", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/exp.3p b/upstream/archlinux/man3p/exp.3p new file mode 100644 index 00000000..56a08d5b --- /dev/null +++ b/upstream/archlinux/man3p/exp.3p @@ -0,0 +1,174 @@ +'\" et +.TH EXP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +exp, +expf, +expl +\(em exponential function +.SH SYNOPSIS +.LP +.nf +#include +.P +double exp(double \fIx\fP); +float expf(float \fIx\fP); +long double expl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the base-\c +.IR e +exponential of +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the +exponential value of +.IR x . +.P +If the correct value would cause overflow, a range error shall occur +and +\fIexp\fR(), +\fIexpf\fR(), +and +\fIexpl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIexp\fR(), +\fIexpf\fR(), +and +\fIexpl\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, 1 shall be returned. +.P +If +.IR x +is \-Inf, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Computing the Density of the Standard Normal Distribution" +.P +This function shows an implementation for the density of the standard +normal distribution using +\fIexp\fR(). +This example uses the constant M_PI which is part of the XSI option. +.sp +.RS 4 +.nf + +#include +.P +double +normal_density (double x) +{ + return exp(-x*x/2) / sqrt (2*M_PI); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/exp2.3p b/upstream/archlinux/man3p/exp2.3p new file mode 100644 index 00000000..23cb8bf4 --- /dev/null +++ b/upstream/archlinux/man3p/exp2.3p @@ -0,0 +1,153 @@ +'\" et +.TH EXP2 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +exp2, +exp2f, +exp2l +\(em exponential base 2 functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double exp2(double \fIx\fP); +float exp2f(float \fIx\fP); +long double exp2l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the base-2 exponential of +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +2\fI\s-3\ux\d\s+3\fR. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIexp2\fR(), +\fIexp2f\fR(), +and +\fIexp2l\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIexp2\fR(), +\fIexp2f\fR(), +and +\fIexp2l\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, 1 shall be returned. +.P +If +.IR x +is \-Inf, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/expm1.3p b/upstream/archlinux/man3p/expm1.3p new file mode 100644 index 00000000..8db897e8 --- /dev/null +++ b/upstream/archlinux/man3p/expm1.3p @@ -0,0 +1,184 @@ +'\" et +.TH EXPM1 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +expm1, +expm1f, +expm1l +\(em compute exponential functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double expm1(double \fIx\fP); +float expm1f(float \fIx\fP); +long double expm1l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute \fIe\u\s-3x\s+3\d\fR\-1.0. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions return +\fIe\s-3\ux\d\s+3\fR\-1.0. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIexpm1\fR(), +\fIexpm1f\fR(), +and +\fIexpm1l\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, \(+-0 shall be returned. +.P +If +.IR x +is \-Inf, \-1 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIexpm1\fR(), +\fIexpm1f\fR(), +and +\fIexpm1l\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The value of +.IR expm1 ( x ) +may be more accurate than +.IR exp ( x )\-1.0 +for small values of +.IR x . +.P +The +\fIexpm1\fR() +and +\fIlog1p\fR() +functions are useful for financial calculations of +((1+\fIx\fR)\u\s-3\fIn\fR\s+3\d\-1)/\fIx\fR, namely: +.sp +.RS 4 +.nf + +expm1(\fIn\fP * log1p(\fIx\fP))/\fIx\fP +.fi +.P +.RE +.P +when +.IR x +is very small (for example, when calculating small daily interest +rates). These functions also simplify writing accurate inverse +hyperbolic functions. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIilogb\fR\^(\|)", +.IR "\fIlog1p\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fabs.3p b/upstream/archlinux/man3p/fabs.3p new file mode 100644 index 00000000..ee81d25b --- /dev/null +++ b/upstream/archlinux/man3p/fabs.3p @@ -0,0 +1,121 @@ +'\" et +.TH FABS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fabs, +fabsf, +fabsl +\(em absolute value function +.SH SYNOPSIS +.LP +.nf +#include +.P +double fabs(double \fIx\fP); +float fabsf(float \fIx\fP); +long double fabsl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the absolute value of their argument +.IR x ,|\c +.IR x |. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the absolute +value of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +0 shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Computing the 1-Norm of a Floating-Point Vector" +.P +This example shows the use of +\fIfabs\fR() +to compute the 1-norm of a vector defined as follows: +.sp +.RS 4 +.nf + +norm1(v) = |v[0]| + |v[1]| + ... + |v[n-1]| +.fi +.P +.RE +.P +where |\fIx\fR| denotes the absolute value of \fIx\fR, \fIn\fR denotes +the vector's dimension \fIv\fR[\fIi\fR] denotes the +.IR i -th +component of \fIv\fR (0\(<=\fIi\fR<\fIn\fR). +.sp +.RS 4 +.nf + +#include +.P +double +norm1(const double v[], const int n) +{ + int i; + double n1_v; /* 1-norm of v */ +.P + n1_v = 0; + for (i=0; i\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/faccessat.3p b/upstream/archlinux/man3p/faccessat.3p new file mode 100644 index 00000000..5c708e8b --- /dev/null +++ b/upstream/archlinux/man3p/faccessat.3p @@ -0,0 +1,41 @@ +'\" et +.TH FACCESSAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +faccessat +\(em determine accessibility of a file relative to directory file +descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int faccessat(int \fIfd\fP, const char *\fIpath\fP, int \fIamode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIaccess\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fattach.3p b/upstream/archlinux/man3p/fattach.3p new file mode 100644 index 00000000..f0b7c9ef --- /dev/null +++ b/upstream/archlinux/man3p/fattach.3p @@ -0,0 +1,236 @@ +'\" et +.TH FATTACH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fattach +\(em attach a STREAMS-based file descriptor to a file in the +file system name space (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int fattach(int \fIfildes\fP, const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIfattach\fR() +function shall attach a STREAMS-based file descriptor to a file, +effectively associating a pathname with +.IR fildes . +The application shall ensure that the +.IR fildes +argument is a valid open file descriptor associated with a STREAMS +file. The +.IR path +argument points to a pathname of an existing file. The application +shall have appropriate privileges or be the owner of the file +named by +.IR path +and have write permission. A successful call to +\fIfattach\fR() +shall cause all pathnames that name the file named by +.IR path +to name the STREAMS file associated with +.IR fildes , +until the STREAMS file is detached from the file. A STREAMS file can be +attached to more than one file and can have several pathnames +associated with it. +.P +The attributes of the named STREAMS file shall be initialized as follows: +the permissions, user ID, group ID, and times are set to those of the +file named by +.IR path , +the number of links is set to 1, and the size and device identifier are +set to those of the STREAMS file associated with +.IR fildes . +If any attributes of the named STREAMS file are subsequently changed +(for example, by +\fIchmod\fR()), +neither the attributes of the underlying file nor the attributes of the +STREAMS file to which +.IR fildes +refers shall be affected. +.P +File descriptors referring to the underlying file, opened prior to an +\fIfattach\fR() +call, shall continue to refer to the underlying file. +.SH "RETURN VALUE" +Upon successful completion, +\fIfattach\fR() +shall return 0. Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfattach\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix, or the +process is the owner of +.IR path +but does not have write permissions on the file named by +.IR path . +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EBUSY +The file named by +.IR path +is currently a mount point or has a STREAMS file attached to it. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. +.TP +.BR EPERM +The effective user ID of the process is not the owner of the file named +by +.IR path +and the process does not have appropriate privileges. +.br +.P +The +\fIfattach\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR fildes +argument does not refer to a STREAMS file. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR EXDEV +A link to a file on another file system was attempted. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Attaching a File Descriptor to a File" +.P +In the following example, +.IR fd +refers to an open STREAMS file. The call to +\fIfattach\fR() +associates this STREAM with the file +.BR /tmp/named-STREAM , +such that any future calls to open +.BR /tmp/named-STREAM , +prior to breaking the attachment via a call to +\fIfdetach\fR(), +will instead create a new file handle referring to the STREAMS file +associated with +.IR fd . +.sp +.RS 4 +.nf + +#include +\&... + int fd; + char *pathname = "/tmp/named-STREAM"; + int ret; +.P + ret = fattach(fd, pathname); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIfattach\fR() +function behaves similarly to the traditional +\fImount\fR() +function in the way a file is temporarily replaced by the root +directory of the mounted file system. In the case of +\fIfattach\fR(), +the replaced file need not be a directory and the replacing file is a +STREAMS file. +.SH RATIONALE +The file attributes of a file which has been the subject of an +\fIfattach\fR() +call are specifically set because of an artifact of the original +implementation. The internal mechanism was the same as for the +\fImount\fR() +function. Since +\fImount\fR() +is typically only applied to directories, the effects when applied to +a regular file are a little surprising, especially as regards the link +count which rigidly remains one, even if there were several links +originally and despite the fact that all original links refer to the +STREAM as long as the +\fIfattach\fR() +remains in effect. +.SH "FUTURE DIRECTIONS" +The +\fIfattach\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfdetach\fR\^(\|)", +.IR "\fIisastream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fchdir.3p b/upstream/archlinux/man3p/fchdir.3p new file mode 100644 index 00000000..5e092cf2 --- /dev/null +++ b/upstream/archlinux/man3p/fchdir.3p @@ -0,0 +1,103 @@ +'\" et +.TH FCHDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fchdir +\(em change working directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchdir(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIfchdir\fR() +function shall be equivalent to +\fIchdir\fR() +except that the directory that is to be the new current working +directory is specified by the file descriptor +.IR fildes . +.P +A conforming application can obtain a file descriptor for a file of +type directory using +\fIopen\fR(), +provided that the file status flags and access modes do not contain +O_WRONLY or O_RDWR. +.SH "RETURN VALUE" +Upon successful completion, +\fIfchdir\fR() +shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. On failure the current working directory +shall remain unchanged. +.SH ERRORS +The +\fIfchdir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for the directory referenced by +.IR fildes . +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR ENOTDIR +The open file descriptor +.IR fildes +does not refer to a directory. +.P +The +\fIfchdir\fR() +may fail if: +.TP +.BR EINTR +A signal was caught during the execution of +\fIfchdir\fR(). +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchdir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fchmod.3p b/upstream/archlinux/man3p/fchmod.3p new file mode 100644 index 00000000..83ca3aeb --- /dev/null +++ b/upstream/archlinux/man3p/fchmod.3p @@ -0,0 +1,161 @@ +'\" et +.TH FCHMOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fchmod +\(em change mode of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchmod(int \fIfildes\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIfchmod\fR() +function shall be equivalent to +\fIchmod\fR() +except that the file whose permissions are changed is specified +by the file descriptor +.IR fildes . +.P +If +.IR fildes +references a shared memory object, the +\fIfchmod\fR() +function need only affect the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, +S_IROTH, and S_IWOTH file permission bits. +.P +If +.IR fildes +references a typed memory object, the behavior of +\fIfchmod\fR() +is unspecified. +.P +If +.IR fildes +refers to a socket, the behavior of +\fIfchmod\fR() +is unspecified. +.P +If +.IR fildes +refers to a STREAM (which is +\fIfattach\fR()-ed +into the file system name space) the call returns successfully, doing +nothing. +.SH "RETURN VALUE" +Upon successful completion, +\fIfchmod\fR() +shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfchmod\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP +.BR EROFS +The file referred to by +.IR fildes +resides on a read-only file system. +.P +The +\fIfchmod\fR() +function may fail if: +.TP +.BR EINTR +The +\fIfchmod\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The value of the +.IR mode +argument is invalid. +.TP +.BR EINVAL +The +.IR fildes +argument refers to a pipe and the implementation disallows execution of +\fIfchmod\fR() +on a pipe. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Permissions for a File" +.P +The following example shows how to change the permissions for a +file named +.BR /home/cnd/mod1 +so that the owner and group have read/write/execute permissions, but +the world only has read/write permissions. +.sp +.RS 4 +.nf + +#include +#include +.P +mode_t mode; +int fildes; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +fchmod(fildes, S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfstatvfs\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fchmodat.3p b/upstream/archlinux/man3p/fchmodat.3p new file mode 100644 index 00000000..ad07110e --- /dev/null +++ b/upstream/archlinux/man3p/fchmodat.3p @@ -0,0 +1,40 @@ +'\" et +.TH FCHMODAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fchmodat +\(em change mode of a file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchmodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIchmod\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fchown.3p b/upstream/archlinux/man3p/fchown.3p new file mode 100644 index 00000000..a54ecbc6 --- /dev/null +++ b/upstream/archlinux/man3p/fchown.3p @@ -0,0 +1,140 @@ +'\" et +.TH FCHOWN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fchown +\(em change owner and group of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchown(int \fIfildes\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +.fi +.SH DESCRIPTION +The +\fIfchown\fR() +function shall be equivalent to +\fIchown\fR() +except that the file whose owner and group are changed is +specified by the file descriptor +.IR fildes . +.SH "RETURN VALUE" +Upon successful completion, +\fIfchown\fR() +shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfchown\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR EPERM +The effective user ID does not match the owner of the file or the +process does not have appropriate privileges and _POSIX_CHOWN_RESTRICTED +indicates that such privilege is required. +.TP +.BR EROFS +The file referred to by +.IR fildes +resides on a read-only file system. +.P +The +\fIfchown\fR() +function may fail if: +.TP +.BR EINVAL +The owner or group ID is not a value supported by the implementation. +The +.IR fildes +argument refers to a pipe or socket +or an +\fIfattach\fR()-ed +STREAM +and the implementation disallows execution of +\fIfchown\fR() +on a pipe. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR EINTR +The +\fIfchown\fR() +function was interrupted by a signal which was caught. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Owner of a File" +.P +The following example shows how to change the owner of a file named +.BR /home/cnd/mod1 +to ``jones'' and the group to ``cnd''. +.P +The numeric value for the user ID is obtained by extracting the user ID +from the user database entry associated with ``jones''. Similarly, the +numeric value for the group ID is obtained by extracting the group ID +from the group database entry associated with ``cnd''. This example +assumes the calling program has appropriate privileges. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +.P +struct passwd *pwd; +struct group *grp; +int fildes; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +pwd = getpwnam("jones"); +grp = getgrnam("cnd"); +fchown(fildes, pwd->pw_uid, grp->gr_gid); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchown\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fchownat.3p b/upstream/archlinux/man3p/fchownat.3p new file mode 100644 index 00000000..47e3f65c --- /dev/null +++ b/upstream/archlinux/man3p/fchownat.3p @@ -0,0 +1,42 @@ +'\" et +.TH FCHOWNAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fchownat +\(em change owner and group of a file relative to directory +file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int fchownat(int \fIfd\fP, const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP, + int \fIflag\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIchown\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fclose.3p b/upstream/archlinux/man3p/fclose.3p new file mode 100644 index 00000000..1ea83b09 --- /dev/null +++ b/upstream/archlinux/man3p/fclose.3p @@ -0,0 +1,206 @@ +'\" et +.TH FCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fclose +\(em close a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fclose(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfclose\fR() +function shall cause the stream pointed to by +.IR stream +to be flushed and the associated file to be closed. Any unwritten +buffered data for the stream shall be written to the file; any unread +buffered data shall be discarded. Whether or not the call succeeds, +the stream shall be disassociated from the file and any buffer set by +the +\fIsetbuf\fR() +or +\fIsetvbuf\fR() +function shall be disassociated from the stream. If the associated +buffer was automatically allocated, it shall be deallocated. +.P +If the file is not already at EOF, and the file is one capable of seeking, +the file offset of the underlying open file description shall be set to +the file position of the stream if the stream is the active handle to +the underlying file description. +.P +The +\fIfclose\fR() +function shall mark for update the last data modification and last +file status change timestamps of the underlying file, if the stream was +writable, and if buffered data remains that has not yet been written to +the file. The +\fIfclose\fR() +function shall perform the equivalent of a +\fIclose\fR() +on the file descriptor that is associated with the stream pointed to by +.IR stream . +.P +After the call to +\fIfclose\fR(), +any use of +.IR stream +results in undefined behavior. +.SH "RETURN VALUE" +Upon successful completion, +\fIfclose\fR() +shall return 0; otherwise, it shall return EOF +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfclose\fR() +function shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying stream is not valid. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or beyond +the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The +\fIfclose\fR() +function was interrupted by a signal. +.TP +.BR EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the calling thread +is not blocking SIGTTOU, the process is not ignoring SIGTTOU, and the +process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOMEM +The underlying stream was created by +\fIopen_memstream\fR() +or +\fIopen_wmemstream\fR() +and insufficient memory is available. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file or +in the buffer used by the +\fIfmemopen\fR() +function. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the +thread. +.P +The +\fIfclose\fR() +function may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since after the call to +\fIfclose\fR() +any use of +.IR stream +results in undefined behavior, +\fIfclose\fR() +should not be used on +.IR stdin , +.IR stdout , +or +.IR stderr +except immediately before process termination (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.303" ", " "Process Termination"), +so as to avoid triggering undefined behavior in other standard +interfaces that rely on these streams. If there are any +\fIatexit\fR() +handlers registered by the application, such a call to +\fIfclose\fR() +should not occur until the last handler is finishing. Once +\fIfclose\fR() +has been used to close +.IR stdin , +.IR stdout , +or +.IR stderr , +there is no standard way to reopen any of these streams. +.P +Use of +\fIfreopen\fR() +to change +.IR stdin , +.IR stdout , +or +.IR stderr +instead of closing them avoids the danger of a file unexpectedly +being opened as one of the special file descriptors STDIN_FILENO, +STDOUT_FILENO, or STDERR_FILENO at a later time in the application. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIatexit\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fcntl.3p b/upstream/archlinux/man3p/fcntl.3p new file mode 100644 index 00000000..82962c87 --- /dev/null +++ b/upstream/archlinux/man3p/fcntl.3p @@ -0,0 +1,756 @@ +'\" et +.TH FCNTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fcntl +\(em file control +.SH SYNOPSIS +.LP +.nf +#include +.P +int fcntl(int \fIfildes\fP, int \fIcmd\fP, ...); +.fi +.SH DESCRIPTION +The +\fIfcntl\fR() +function shall perform the operations described below on open files. The +.IR fildes +argument is a file descriptor. +.P +The available values for +.IR cmd +are defined in +.IR +and are as follows: +.IP F_DUPFD 14 +Return a new file descriptor which shall be allocated as described in +.IR "Section 2.14" ", " "File Descriptor Allocation", +except that it shall be the lowest numbered available file +descriptor greater than or equal to the third argument, +.IR arg , +taken as an integer of type +.BR int . +The new file descriptor shall refer to the same open file description as +the original file descriptor, and shall share any locks. The FD_CLOEXEC +flag associated with the new file descriptor shall be cleared to keep +the file open across calls to one of the +.IR exec +functions. +.IP F_DUPFD_CLOEXEC 14 +.br +Like F_DUPFD, but the FD_CLOEXEC flag associated with the new file +descriptor shall be set. +.IP F_GETFD 14 +Get the file descriptor flags defined in +.IR +that are associated with the file descriptor +.IR fildes . +File descriptor flags are associated with a single file descriptor and +do not affect other file descriptors that refer to the same file. +.IP F_SETFD 14 +Set the file descriptor flags defined in +.IR , +that are associated with +.IR fildes , +to the third argument, +.IR arg , +taken as type +.BR int . +If the FD_CLOEXEC flag in the third argument +is 0, the file descriptor shall remain open across the +.IR exec +functions; otherwise, the file descriptor shall be closed upon +successful execution of one of the +.IR exec +functions. +.IP F_GETFL 14 +Get the file status flags and file access modes, defined in +.IR , +for the file description associated with +.IR fildes . +The file access modes can be extracted from the return value using the +mask O_ACCMODE, which is defined in +.IR . +File status flags and file access modes are associated with the file +description and do not affect other file descriptors that refer to the +same file with different open file descriptions. The flags returned may +include non-standard file status flags which the application did not +set, provided that these additional flags do not alter the behavior of +a conforming application. +.IP F_SETFL 14 +Set the file status flags, defined in +.IR , +for the file description associated with +.IR fildes +from the corresponding bits in the third argument, +.IR arg , +taken as type +.BR int . +Bits corresponding to the file access mode and the file creation +flags, as defined in +.IR , +that are set in +.IR arg +shall be ignored. If any bits in +.IR arg +other than those mentioned here are changed by the application, the +result is unspecified. If +.IR fildes +does not support non-blocking operations, it is unspecified whether the +O_NONBLOCK flag will be ignored. +.IP F_GETOWN 14 +If +.IR fildes +refers to a socket, get the process ID or process group ID specified to +receive SIGURG signals when out-of-band data is available. Positive +values shall indicate a process ID; negative values, other than \-1, +shall indicate a process group ID; the value zero shall indicate +that no SIGURG signals are to be sent. If +.IR fildes +does not refer to a socket, the results are unspecified. +.IP F_SETOWN 14 +If +.IR fildes +refers to a socket, set the process ID or process group ID specified to +receive SIGURG signals when out-of-band data is available, using the +value of the third argument, +.IR arg , +taken as type +.BR int . +Positive values shall indicate a process ID; negative values, +other than \-1, shall indicate a process group ID; the value zero +shall indicate that no SIGURG signals are to be sent. Each time a +SIGURG signal is sent to the specified process or process group, +permission checks equivalent to those performed by +\fIkill\fR() +shall be performed, as if +\fIkill\fR() +were called by a process with the same real user ID, effective +user ID, and privileges that the process calling +\fIfcntl\fR() +has at the time of the call; if the +\fIkill\fR() +call would fail, no signal shall be sent. These permission checks may +also be performed by the +\fIfcntl\fR() +call. If the process specified by +.IR arg +later terminates, or the process group specified by +.IR arg +later becomes empty, while still being specified to receive +SIGURG signals when out-of-band data is available from +.IR fildes , +then no signals shall be sent to any subsequently created process +that has the same process ID or process group ID, regardless of +permission; it is unspecified whether this is achieved by the +equivalent of a +.IR fcntl ( fildes ", F_SETOWN, 0)" +call at the time the process terminates or is waited for or the +process group becomes empty, or by other means. If +.IR fildes +does not refer to a socket, the results are unspecified. +.P +The following values for +.IR cmd +are available for advisory record locking. Record locking shall be +supported for regular files, and may be supported for other files. +.IP F_GETLK 14 +Get any lock which blocks the lock description pointed to by the +third argument, +.IR arg , +taken as a pointer to type +.BR "struct flock" , +defined in +.IR . +The information retrieved shall overwrite the information passed to +\fIfcntl\fR() +in the structure +.BR flock . +If no lock is found that would prevent this lock from being created, +then the structure shall be left unchanged except for the lock type +which shall be set to F_UNLCK. +.IP F_SETLK 14 +Set or clear a file segment lock according to the lock description +pointed to by the third argument, +.IR arg , +taken as a pointer to type +.BR "struct flock" , +defined in +.IR . +F_SETLK can establish shared (or read) locks (F_RDLCK) or +exclusive (or write) locks (F_WRLCK), as well as to remove either type +of lock (F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in +.IR . +If a shared or exclusive lock cannot be set, +\fIfcntl\fR() +shall return immediately with a return value of \-1. +.IP F_SETLKW 14 +This command shall be equivalent to F_SETLK except that if a shared or +exclusive lock is blocked by other locks, the thread shall wait until +the request can be satisfied. If a signal that is to be caught is +received while +\fIfcntl\fR() +is waiting for a region, +\fIfcntl\fR() +shall be interrupted. Upon return from the signal handler, +\fIfcntl\fR() +shall return \-1 with +.IR errno +set to +.BR [EINTR] , +and the lock operation shall not be done. +.P +Additional implementation-defined values for +.IR cmd +may be defined in +.IR . +Their names shall start with F_. +.P +When a shared lock is set on a segment of a file, other processes shall +be able to 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 +shall fail if the file descriptor was not opened with read access. +.P +An exclusive lock shall prevent 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 shall fail if the file descriptor was not +opened with write access. +.P +The structure +.BR flock +describes the type (\c +.IR l_type ), +starting offset (\c +.IR l_whence ), +relative offset (\c +.IR l_start ), +size (\c +.IR l_len ), +and process ID (\c +.IR l_pid ) +of the segment of the file to be affected. +.P +The value of +.IR l_whence +is SEEK_SET, SEEK_CUR, or SEEK_END, +to indicate that the relative offset +.IR l_start +bytes shall be measured from the start of the file, current position, +or end of the file, respectively. The value of +.IR l_len +is the number of consecutive bytes to be locked. The value of +.IR l_len +may be negative (where the definition of +.BR off_t +permits negative values of +.IR l_len ). +The +.IR l_pid +field is only used with F_GETLK to return the process ID of the process +holding a blocking lock. After a successful F_GETLK request, when a +blocking lock is found, the values returned in the +.BR flock +structure shall be as follows: +.IP "\fIl_type\fP" 10 +Type of blocking lock found. +.IP "\fIl_whence\fP" 10 +SEEK_SET. +.IP "\fIl_start\fP" 10 +Start of the blocking lock. +.IP "\fIl_len\fP" 10 +Length of the blocking lock. +.IP "\fIl_pid\fP" 10 +Process ID of the process that holds the blocking lock. +.P +If the command is F_SETLKW and the process must wait for another +process to release a lock, then the range of bytes to be locked shall +be determined before the +\fIfcntl\fR() +function blocks. If the file size or file descriptor seek offset change +while +\fIfcntl\fR() +is blocked, this shall not affect the range of bytes locked. +.P +If +.IR l_len +is positive, the area affected shall start at +.IR l_start +and end at +.IR l_start +\c +.IR l_len \-1. +If +.IR l_len +is negative, the area affected shall start at +.IR l_start +\c +.IR l_len +and end at +.IR l_start \-1. +Locks may start and extend beyond the current end of a file, but shall +not extend before the beginning of the file. A lock shall be set to +extend to the largest possible value of the file offset for that file +by setting +.IR l_len +to 0. If such a lock also has +.IR l_start +set to 0 and +.IR l_whence +is set to SEEK_SET, the whole file shall be locked. +.P +There shall be at most one type of lock set for each byte in the file. +Before a successful return from an F_SETLK or an 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 shall be replaced by the new lock type. As +specified above under the descriptions of shared locks and exclusive +locks, an F_SETLK or an F_SETLKW request (respectively) shall fail or +block 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. +.P +All locks associated with a file for a given process shall be removed +when a file descriptor for that file is closed by that process or the +process holding that file descriptor terminates. Locks are not +inherited by a child process. +.P +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. If the system detects that sleeping until a locked +region is unlocked would cause a deadlock, +\fIfcntl\fR() +shall fail with an +.BR [EDEADLK] +error. +.P +An unlock (F_UNLCK) request in which +.IR l_len +is non-zero and the offset of the last byte of the requested segment is +the maximum value for an object of type +.BR off_t , +when the process has an existing lock in which +.IR l_len +is 0 and which includes the last byte of the requested segment, shall be +treated as a request to unlock from the start of the requested segment +with an +.IR l_len +equal to 0. Otherwise, an unlock (F_UNLCK) request shall attempt to +unlock only the requested segment. +.P +When the file descriptor +.IR fildes +refers to a shared memory object, the behavior of +\fIfcntl\fR() +shall be the same as for a regular file except the effect of the +following values for the argument +.IR cmd +shall be unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIfcntl\fR() +function is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the value returned shall depend on +.IR cmd +as follows: +.IP F_DUPFD 12 +A new file descriptor. +.IP F_DUPFD_CLOEXEC 12 +.br +A new file descriptor. +.IP F_GETFD 12 +Value of flags defined in +.IR . +The return value shall not be negative. +.IP F_SETFD 12 +Value other than \-1. +.IP F_GETFL 12 +Value of file status flags and access modes. The return value is not +negative. +.IP F_SETFL 12 +Value other than \-1. +.IP F_GETLK 12 +Value other than \-1. +.IP F_SETLK 12 +Value other than \-1. +.IP F_SETLKW 12 +Value other than \-1. +.IP F_GETOWN 12 +Value of the socket owner process or process group; this will not be +\-1. +.IP F_SETOWN 12 +Value other than \-1. +.P +Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfcntl\fR() +function shall fail if: +.TP +.BR EACCES " or " EAGAIN +.br +The +.IR cmd +argument is F_SETLK; the type of lock (\c +.IR l_type ) +is a shared (F_RDLCK) or exclusive (F_WRLCK) lock 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. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor, or the argument +.IR cmd +is F_SETLK or F_SETLKW, the type of lock, +.IR l_type , +is a shared lock (F_RDLCK), and +.IR fildes +is not a valid file descriptor open for reading, or the type of lock, +.IR l_type , +is an exclusive lock (F_WRLCK), and +.IR fildes +is not a valid file descriptor open for writing. +.TP +.BR EINTR +The +.IR cmd +argument is F_SETLKW and the function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR cmd +argument is invalid, or the +.IR cmd +argument is F_DUPFD or F_DUPFD_CLOEXEC and +.IR arg +is negative or greater than or equal to +{OPEN_MAX}, +or the +.IR cmd +argument is F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by +.IR arg +is not valid, or +.IR fildes +refers to a file that does not support locking. +.TP +.BR EMFILE +The argument +.IR cmd +is F_DUPFD or F_DUPFD_CLOEXEC and all file descriptors available to +the process are currently open, or no file descriptors greater than or +equal to +.IR arg +are available. +.TP +.BR ENOLCK +The argument +.IR cmd +is F_SETLK or 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. +.TP +.BR EOVERFLOW +One of the values to be returned cannot be represented correctly. +.TP +.BR EOVERFLOW +The +.IR cmd +argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if +.IR l_len +is non-zero, the largest offset of any byte in the requested segment +cannot be represented correctly in an object of type +.BR off_t . +.TP +.BR ESRCH +The +.IR cmd +argument is F_SETOWN and no process or process group can be found +corresponding to that specified by +.IR arg . +.br +.P +The +\fIfcntl\fR() +function may fail if: +.TP +.BR EDEADLK +The +.IR cmd +argument is F_SETLKW, the lock is blocked by a lock from another +process, and putting the calling process to sleep to wait for that lock +to become free would cause a deadlock. +.TP +.BR EINVAL +The +.IR cmd +argument is F_SETOWN and the value of the argument is not valid as a +process or process group identifier. +.TP +.BR EPERM +The +.IR cmd +argument is F_SETOWN and the calling process does not have +permission to send a SIGURG signal to any process specified by +.IR arg . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Locking and Unlocking a File" +.P +The following example demonstrates how to place a lock on bytes 100 to +109 of a file and then later remove it. F_SETLK is used to perform a +non-blocking lock request so that the process does not have to wait if +an incompatible lock is held by another process; instead the process +can take some other action. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +.P +int +main(int argc, char *argv[]) +{ + int fd; + struct flock fl; +.P + fd = open("testfile", O_RDWR); + if (fd == -1) + /* Handle error */; +.P + /* Make a non-blocking request to place a write lock + on bytes 100-109 of testfile */ +.P + fl.l_type = F_WRLCK; + fl.l_whence = SEEK_SET; + fl.l_start = 100; + fl.l_len = 10; +.P + if (fcntl(fd, F_SETLK, &fl) == -1) { + if (errno == EACCES || errno == EAGAIN) { + printf("Already locked by another process\en"); +.P + /* We cannot get the lock at the moment */ +.P + } else { + /* Handle unexpected error */; + } + } else { /* Lock was granted... */ +.P + /* Perform I/O on bytes 100 to 109 of file */ +.P + /* Unlock the locked bytes */ +.P + fl.l_type = F_UNLCK; + fl.l_whence = SEEK_SET; + fl.l_start = 100; + fl.l_len = 10; + if (fcntl(fd, F_SETLK, &fl) == -1) + /* Handle error */; + } + exit(EXIT_SUCCESS); +} /* main */ +.fi +.P +.RE +.SS "Setting the Close-on-Exec Flag" +.P +The following example demonstrates how to set the close-on-exec flag +for the file descriptor +.IR fd . +.sp +.RS 4 +.nf + +#include +#include +\&... + int flags; +.P + flags = fcntl(fd, F_GETFD); + if (flags == -1) + /* Handle error */; + flags |= FD_CLOEXEC; + if (fcntl(fd, F_SETFD, flags) == -1) + /* Handle error */;" +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +.IR arg +values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag +values to allow for future growth. Applications using these functions +should do a read-modify-write operation on them, rather than assuming +that only the values defined by this volume of POSIX.1\(hy2017 are valid. It is a common error to +forget this, particularly in the case of F_SETFD. Some implementations +set additional file status flags to advise the application of default +behavior, even though the application did not request these flags. +.P +On systems which do not perform permission checks at the time of an +\fIfcntl\fR() +call with F_SETOWN, if the permission checks performed at the time +the signal is sent disallow sending the signal to any process, +the process that called +\fIfcntl\fR() +has no way of discovering that this has happened. A call to +\fIkill\fR() +with signal 0 can be used as a prior check of permissions, although +this is no guarantee that permission will be granted at the time +a signal is sent, since the target process(es) could change +user IDs or privileges in the meantime. +.SH RATIONALE +The ellipsis in the SYNOPSIS is the syntax specified by the ISO\ C standard +for a variable number of arguments. It is used because System V uses +pointers for the implementation of file locking functions. +.P +This volume of POSIX.1\(hy2017 permits concurrent read and write access to file data using the +\fIfcntl\fR() +function; this is a change from the 1984 /usr/group standard and early proposals. Without +concurrency controls, this feature may not be fully utilized without +occasional loss of data. +.P +Data losses occur in several ways. One case occurs when several +processes try to update the same record, without sequencing controls; +several updates may occur in parallel and the last writer ``wins''. +Another case is a bit-tree or other internal list-based database that +is undergoing reorganization. Without exclusive use to the tree segment +by the updating process, other reading processes chance getting lost in +the database when the index blocks are split, condensed, inserted, or +deleted. While +\fIfcntl\fR() +is useful for many applications, it is not intended to be overly +general and does not handle the bit-tree example well. +.P +This facility is only required for regular files because it is not +appropriate for many devices such as terminals and network +connections. +.P +Since +\fIfcntl\fR() +works with ``any file descriptor associated with that file, however it +is obtained'', the file descriptor may have been inherited through a +\fIfork\fR() +or +.IR exec +operation and thus may affect a file that another process also has +open. +.P +The use of the open file description to identify what to lock requires +extra calls and presents problems if several processes are sharing an +open file description, but there are too many implementations of the +existing mechanism for this volume of POSIX.1\(hy2017 to use different specifications. +.P +Another consequence of this model is that closing any file descriptor +for a given file (whether or not it is the same open file description +that created the lock) causes the locks on that file to be relinquished +for that process. Equivalently, any close for any file/process pair +relinquishes the locks owned on that file for that process. But note +that while an open file description may be shared through +\fIfork\fR(), +locks are not inherited through +\fIfork\fR(). +Yet locks may be inherited through one of the +.IR exec +functions. +.P +The identification of a machine in a network environment is outside +the scope of this volume of POSIX.1\(hy2017. Thus, an +.IR l_sysid +member, such as found in System V, is not included in the locking +structure. +.P +Changing of lock types can result in a previously locked region being +split into smaller regions. +.P +Mandatory locking was a major feature of the 1984 /usr/group standard. +.P +For advisory file record locking to be effective, all processes that +have access to a file must cooperate and use the advisory mechanism +before doing I/O on the file. Enforcement-mode record locking is +important when it cannot be assumed that all processes are cooperating. +For example, if one user uses an editor to update a file at the same +time that a second user executes another process that updates the same +file and if only one of the two processes is using advisory locking, +the processes are not cooperating. Enforcement-mode record locking +would protect against accidental collisions. +.P +Secondly, advisory record locking requires a process using locking to +bracket each I/O operation with lock (or test) and unlock operations. +With enforcement-mode file and record locking, a process can lock the +file once and unlock when all I/O operations have been completed. +Enforcement-mode record locking provides a base that can be enhanced; +for example, with sharable locks. That is, the mechanism could be +enhanced to allow a process to lock a file so other processes could +read it, but none of them could write it. +.P +Mandatory locks were omitted for several reasons: +.IP " 1." 4 +Mandatory lock setting was done by multiplexing the set-group-ID +bit in most implementations; this was confusing, at best. +.IP " 2." 4 +The relationship to file truncation as supported in 4.2 BSD +was not well specified. +.IP " 3." 4 +Any publicly readable file could be locked by anyone. Many historical +implementations keep the password database in a publicly readable +file. A malicious user could thus prohibit logins. Another +possibility would be to hold open a long-distance telephone line. +.IP " 4." 4 +Some demand-paged historical implementations offer memory mapped files, +and enforcement cannot be done on that type of file. +.P +Since sleeping on a region is interrupted with any signal, +\fIalarm\fR() +may be used to provide a timeout facility in applications requiring +it. This is useful in deadlock detection. Since implementation of +full deadlock detection is not always feasible, the +.BR [EDEADLK] +error was made optional. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIkill\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fdatasync.3p b/upstream/archlinux/man3p/fdatasync.3p new file mode 100644 index 00000000..ab7c8172 --- /dev/null +++ b/upstream/archlinux/man3p/fdatasync.3p @@ -0,0 +1,103 @@ +'\" et +.TH FDATASYNC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fdatasync +\(em synchronize the data of a file +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int fdatasync(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIfdatasync\fR() +function shall force all currently queued I/O operations associated +with the file indicated by file descriptor +.IR fildes +to the synchronized I/O completion state. +.P +The functionality shall be equivalent to +\fIfsync\fR() +with the symbol _POSIX_SYNCHRONIZED_IO defined, +with the exception that all I/O operations shall be completed as +defined for synchronized I/O data integrity completion. +.SH "RETURN VALUE" +If successful, the +\fIfdatasync\fR() +function shall return the value 0; otherwise, the function shall return +the value \-1 and set +.IR errno +to indicate the error. If the +\fIfdatasync\fR() +function fails, outstanding I/O operations are not guaranteed to have +been completed. +.SH ERRORS +The +\fIfdatasync\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +This implementation does not support synchronized I/O for this file. +.P +In the event that any of the queued I/O operations fail, +\fIfdatasync\fR() +shall return the error conditions defined for +\fIread\fR() +and +\fIwrite\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Note that even if the file descriptor is not open for writing, +if there are any pending write requests on the underlying file, +then that I/O will be completed prior to the return of +\fIfdatasync\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_fsync\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfsync\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fdetach.3p b/upstream/archlinux/man3p/fdetach.3p new file mode 100644 index 00000000..3f074a7c --- /dev/null +++ b/upstream/archlinux/man3p/fdetach.3p @@ -0,0 +1,176 @@ +'\" et +.TH FDETACH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fdetach +\(em detach a name from a STREAMS-based file descriptor (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int fdetach(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIfdetach\fR() +function shall detach a STREAMS-based file from the file to which +it was attached by a previous call to +\fIfattach\fR(). +The +.IR path +argument points to the pathname of the attached STREAMS file. The +process shall have appropriate privileges or be the owner of the file. +A successful call to +\fIfdetach\fR() +shall cause all pathnames that named the attached STREAMS file to again +name the file to which the STREAMS file was attached. All subsequent +operations on +.IR path +shall operate on the underlying file and not on the STREAMS file. +.P +All open file descriptions established while the STREAMS file was +attached to the file referenced by +.IR path +shall still refer to the STREAMS file after the +\fIfdetach\fR() +has taken effect. +.P +If there are no open file descriptors or other references to the +STREAMS file, then a successful call to +\fIfdetach\fR() +shall be equivalent to performing the last +\fIclose\fR() +on the attached file. +.SH "RETURN VALUE" +Upon successful completion, +\fIfdetach\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfdetach\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR EINVAL +The +.IR path +argument names a file that is not currently attached. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID is not the owner of +.IR path +and the process does not have appropriate privileges. +.P +The +\fIfdetach\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Detaching a File" +.P +The following example detaches the STREAMS-based file +.BR /tmp/named-STREAM +from the file to which it was attached by a previous, successful call +to +\fIfattach\fR(). +Subsequent calls to open this file refer to the underlying file, not to +the STREAMS file. +.sp +.RS 4 +.nf + +#include +\&... + char *pathname = "/tmp/named-STREAM"; + int ret; +.P + ret = fdetach(pathname); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIfdetach\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfattach\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fdim.3p b/upstream/archlinux/man3p/fdim.3p new file mode 100644 index 00000000..4068641b --- /dev/null +++ b/upstream/archlinux/man3p/fdim.3p @@ -0,0 +1,150 @@ +'\" et +.TH FDIM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fdim, +fdimf, +fdiml +\(em compute positive difference between two floating-point numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double fdim(double \fIx\fP, double \fIy\fP); +float fdimf(float \fIx\fP, float \fIy\fP); +long double fdiml(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall determine the positive difference between their +arguments. If +.IR x +is greater than +.IR y , +.IR x \-\c +.IR y +is returned. If +.IR x +is less than or equal to +.IR y , ++0 is returned. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the positive +difference value. +.P +If +.IR x \-\c +.IR y +is positive and overflows, a range error shall occur and +\fIfdim\fR(), +\fIfdimf\fR(), +and +\fIfdiml\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If the correct value would cause underflow, a range error may occur, and +\fIfdim\fR(), +\fIfdimf\fR(), +and +\fIfdiml\fR() +shall return +the correct value, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.SH ERRORS +The +\fIfdim\fR() +function shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +The +\fIfdim\fR() +function may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfmax\fR\^(\|)", +.IR "\fIfmin\fR\^(\|)" +.P +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fdopen.3p b/upstream/archlinux/man3p/fdopen.3p new file mode 100644 index 00000000..0b8a1555 --- /dev/null +++ b/upstream/archlinux/man3p/fdopen.3p @@ -0,0 +1,196 @@ +'\" et +.TH FDOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fdopen +\(em associate a stream with a file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *fdopen(int \fIfildes\fP, const char *\fImode\fP); +.fi +.SH DESCRIPTION +The +\fIfdopen\fR() +function shall associate a stream with a file descriptor. +.P +The +.IR mode +argument is a character string having one of the following values: +.IP "\fIr\fP\ or\ \fIrb\fP" 14 +Open a file for reading. +.IP "\fIw\fP\ or\ \fIwb\fP" 14 +Open a file for writing. +.IP "\fIa\fP\ or\ \fIab\fP" 14 +Open a file for writing at end-of-file. +.IP "\fIr\fP+\ or\ \fIrb\fP+\ or\ \fIr\fP+\fIb\fP" 14 +Open a file for update (reading and writing). +.IP "\fIw\fP+\ or\ \fIwb\fP+\ or\ \fIw\fP+\fIb\fP" 14 +Open a file for update (reading and writing). +.IP "\fIa\fP+\ or\ \fIab\fP+\ or\ \fIa\fP+\fIb\fP" 14 +Open a file for update (reading and writing) at end-of-file. +.P +The meaning of these flags is exactly as specified in +\fIfopen\fR(), +except that modes beginning with +.IR w +shall not cause truncation of the file. +.P +Additional values for the +.IR mode +argument may be supported by an implementation. +.P +The application shall ensure that the mode of the stream as expressed +by the +.IR mode +argument is allowed by the file access mode of the open file +description to which +.IR fildes +refers. The file position indicator associated with the new stream is +set to the position indicated by the file offset associated with the +file descriptor. +.P +The error and end-of-file indicators for the stream shall be cleared. +The +\fIfdopen\fR() +function may cause the last data access timestamp of the underlying +file to be marked for update. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIfdopen\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIfdopen\fR() +function is unspecified. +.P +The +\fIfdopen\fR() +function shall preserve the offset maximum previously set for the +open file description corresponding to +.IR fildes . +.SH "RETURN VALUE" +Upon successful completion, +\fIfdopen\fR() +shall return a pointer to a stream; otherwise, a null pointer shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfdopen\fR() +function shall fail if: +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.P +The +\fIfdopen\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR mode +argument is not a valid mode. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENOMEM +Insufficient space to allocate a buffer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +File descriptors are obtained from calls like +\fIopen\fR(), +\fIdup\fR(), +\fIcreat\fR(), +or +\fIpipe\fR(), +which open files but do not return streams. +.SH RATIONALE +The file descriptor may have been obtained from +\fIopen\fR(), +\fIcreat\fR(), +\fIpipe\fR(), +\fIdup\fR(), +\fIfcntl\fR(), +or +\fIsocket\fR(); +inherited through +\fIfork\fR(), +\fIposix_spawn\fR(), +or +.IR exec ; +or perhaps obtained by other means. +.P +The meanings of the +.IR mode +arguments of +\fIfdopen\fR() +and +\fIfopen\fR() +differ. With +\fIfdopen\fR(), +open for write (\fIw\fP or \fIw+\fP) does not truncate, and append +(\fIa\fP or \fIa+\fP) cannot create for writing. The +.IR mode +argument formats that include a \fIb\fP are allowed for consistency +with the ISO\ C standard function +\fIfopen\fR(). +The \fIb\fP has no effect on the resulting stream. Although not +explicitly required by this volume of POSIX.1\(hy2017, a good implementation of append (\fIa\fP) +mode would cause the O_APPEND flag to be set. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fdopendir.3p b/upstream/archlinux/man3p/fdopendir.3p new file mode 100644 index 00000000..e8ecbadb --- /dev/null +++ b/upstream/archlinux/man3p/fdopendir.3p @@ -0,0 +1,316 @@ +'\" et +.TH FDOPENDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fdopendir, opendir +\(em open directory associated with file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +DIR *fdopendir(int \fIfd\fP); +DIR *opendir(const char *\fIdirname\fP); +.fi +.SH DESCRIPTION +The +\fIfdopendir\fR() +function shall be equivalent to the +\fIopendir\fR() +function except that the directory is specified by a file descriptor +rather than by a name. The file offset associated with the file +descriptor at the time of the call determines which entries are +returned. +.P +Upon successful return from +\fIfdopendir\fR(), +the file descriptor is under the control of the system, and if any +attempt is made to close the file descriptor, or to modify the state of +the associated description, other than by means of +\fIclosedir\fR(), +\fIreaddir\fR(), +\fIreaddir_r\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(), +the behavior is undefined. Upon calling +\fIclosedir\fR() +the file descriptor shall be closed. +.P +It is unspecified whether the FD_CLOEXEC flag will be set on the file +descriptor by a successful call to +\fIfdopendir\fR(). +.P +The +\fIopendir\fR() +function shall open a directory stream corresponding to the directory +named by the +.IR dirname +argument. The directory stream is positioned at the first entry. If +the type +.BR DIR +is implemented using a file descriptor, applications shall only be +able to open up to a total of +{OPEN_MAX} +files and directories. +.P +If the type +.BR DIR +is implemented using a file descriptor, the descriptor shall be +obtained as if the O_DIRECTORY flag was passed to +\fIopen\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +a pointer to an object of type +.BR DIR . +Otherwise, these functions shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfdopendir\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor open for reading. +.TP +.BR ENOTDIR +The descriptor +.IR fd +is not associated with a directory. +.P +The +\fIopendir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for the component of the path prefix of +.IR dirname +or read permission is denied for +.IR dirname . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR dirname +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR dirname +does not name an existing directory or +.IR dirname +is an empty string. +.TP +.BR ENOTDIR +A component of +.IR dirname +names an existing file that is neither a directory nor a symbolic link +to a directory. +.br +.P +The +\fIopendir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR dirname +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Open a Directory Stream" +.P +The following program fragment demonstrates how the +\fIopendir\fR() +function is used. +.sp +.RS 4 +.nf + +#include +\&... + DIR *dir; + struct dirent *dp; +\&... + if ((dir = opendir (".")) == NULL) { + perror ("Cannot open ."); + exit (1); + } +.P + while ((dp = readdir (dir)) != NULL) { +\&... +.fi +.P +.RE +.SS "Find And Open a File" +.P +The following program searches through a given directory looking +for files whose name does not begin with a dot and whose size is +larger than 1 MiB. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +#include +.P +int +main(int argc, char *argv[]) +{ + struct stat statbuf; + DIR *d; + struct dirent *dp; + int dfd, ffd; +.P + if ((d = fdopendir((dfd = open("./tmp", O_RDONLY)))) == NULL) { + fprintf(stderr, "Cannot open ./tmp directory\en"); + exit(1); + } + while ((dp = readdir(d)) != NULL) { + if (dp->d_name[0] == \(aq.\(aq) + continue; + /* there is a possible race condition here as the file + * could be renamed between the readdir and the open */ + if ((ffd = openat(dfd, dp->d_name, O_RDONLY)) == -1) { + perror(dp->d_name); + continue; + } + if (fstat(ffd, &statbuf) == 0 && statbuf.st_size > (1024*1024)) { + /* found it ... */ + printf("%s: %jdK\en", dp->d_name, + (intmax_t)(statbuf.st_size / 1024)); + } + close(ffd); + } + closedir(d); // note this implicitly closes dfd + return 0; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIopendir\fR() +function should be used in conjunction with +\fIreaddir\fR(), +\fIclosedir\fR(), +and +\fIrewinddir\fR() +to examine the contents of the directory (see the EXAMPLES section in +.IR "\fIreaddir\fR\^(\|)"). +This method is recommended for portability. +.SH RATIONALE +The purpose of the +\fIfdopendir\fR() +function is to enable opening files in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIopendir\fR(), +resulting in unspecified behavior. +.P +Based on historical implementations, the rules about file descriptors +apply to directory streams as well. However, this volume of POSIX.1\(hy2017 does not +mandate that the directory stream be implemented using file +descriptors. The description of +\fIclosedir\fR() +clarifies that if a file descriptor is used for the directory stream, +it is mandatory that +\fIclosedir\fR() +deallocate the file descriptor. When a file descriptor is used to +implement the directory stream, it behaves as if the FD_CLOEXEC +had been set for the file descriptor. +.P +The directory entries for dot +and dot-dot +are optional. This volume of POSIX.1\(hy2017 does not provide a way to test +.IR "a priori" +for their existence because an application that is portable must be +written to look for (and usually ignore) those entries. Writing code +that presumes that they are the first two entries does not always work, +as many implementations permit them to be other than the first two +entries, with a ``normal'' entry preceding them. There is negligible +value in providing a way to determine what the implementation does +because the code to deal with dot and dot-dot must be written in any +case and because such a flag would add to the list of those flags +(which has proven in itself to be objectionable) and might be abused. +.P +Since the structure and buffer allocation, if any, for directory +operations are defined by the implementation, this volume of POSIX.1\(hy2017 imposes no +portability requirements for erroneous program constructs, erroneous +data, or the use of unspecified values such as the use or referencing +of a +.IR dirp +value or a +.BR dirent +structure value after a directory stream has been closed or after a +\fIfork\fR() +or one of the +.IR exec +function calls. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIrewinddir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/feclearexcept.3p b/upstream/archlinux/man3p/feclearexcept.3p new file mode 100644 index 00000000..30f19431 --- /dev/null +++ b/upstream/archlinux/man3p/feclearexcept.3p @@ -0,0 +1,71 @@ +'\" et +.TH FECLEAREXCEPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +feclearexcept +\(em clear floating-point exception +.SH SYNOPSIS +.LP +.nf +#include +.P +int feclearexcept(int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfeclearexcept\fR() +function shall attempt to clear the supported floating-point +exceptions represented by +.IR excepts . +.SH "RETURN VALUE" +If the argument is zero or if all the specified exceptions were +successfully cleared, +\fIfeclearexcept\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fegetenv.3p b/upstream/archlinux/man3p/fegetenv.3p new file mode 100644 index 00000000..341ca47d --- /dev/null +++ b/upstream/archlinux/man3p/fegetenv.3p @@ -0,0 +1,91 @@ +'\" et +.TH FEGETENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fegetenv, +fesetenv +\(em get and set current floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int fegetenv(fenv_t *\fIenvp\fP); +int fesetenv(const fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfegetenv\fR() +function shall attempt to store the current floating-point environment +in the object pointed to by +.IR envp . +.P +The +\fIfesetenv\fR() +function shall attempt to establish the floating-point environment +represented by the object pointed to by +.IR envp . +The argument +.IR envp +shall point to an object set by a call to +\fIfegetenv\fR() +or +\fIfeholdexcept\fR(), +or equal a floating-point environment macro. The +\fIfesetenv\fR() +function does not raise floating-point exceptions, but only installs +the state of the floating-point status flags represented through its +argument. +.SH "RETURN VALUE" +If the representation was successfully stored, +\fIfegetenv\fR() +shall return zero. Otherwise, it shall return a non-zero value. +If the environment was successfully established, +\fIfesetenv\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeholdexcept\fR\^(\|)", +.IR "\fIfeupdateenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fegetexceptflag.3p b/upstream/archlinux/man3p/fegetexceptflag.3p new file mode 100644 index 00000000..9d165355 --- /dev/null +++ b/upstream/archlinux/man3p/fegetexceptflag.3p @@ -0,0 +1,96 @@ +'\" et +.TH FEGETEXCEPTFLAG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fegetexceptflag, +fesetexceptflag +\(em get and set floating-point status flags +.SH SYNOPSIS +.LP +.nf +#include +.P +int fegetexceptflag(fexcept_t *\fIflagp\fP, int \fIexcepts\fP); +int fesetexceptflag(const fexcept_t *\fIflagp\fP, int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfegetexceptflag\fR() +function shall attempt to store an implementation-defined representation +of the states of the floating-point status flags indicated by the argument +.IR excepts +in the object pointed to by the argument +.IR flagp . +.P +The +\fIfesetexceptflag\fR() +function shall attempt to set the floating-point status flags indicated +by the argument +.IR excepts +to the states stored in the object pointed to by +.IR flagp . +The value pointed to by +.IR flagp +shall have been set by a previous call to +\fIfegetexceptflag\fR() +whose second argument represented at least those floating-point +exceptions represented by the argument +.IR excepts . +This function does not raise floating-point exceptions, but only sets +the state of the flags. +.SH "RETURN VALUE" +If the representation was successfully stored, +\fIfegetexceptflag\fR() +shall return zero. Otherwise, it shall return a non-zero value. If the +.IR excepts +argument is zero or if all the specified exceptions were successfully +set, +\fIfesetexceptflag\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fegetround.3p b/upstream/archlinux/man3p/fegetround.3p new file mode 100644 index 00000000..52b4f837 --- /dev/null +++ b/upstream/archlinux/man3p/fegetround.3p @@ -0,0 +1,105 @@ +'\" et +.TH FEGETROUND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fegetround, +fesetround +\(em get and set current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +int fegetround(void); +int fesetround(int \fIround\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfegetround\fR() +function shall get the current rounding direction. +.P +The +\fIfesetround\fR() +function shall establish the rounding direction represented by its +argument +.IR round . +If the argument is not equal to the value of a rounding direction +macro, the rounding direction is not changed. +.SH "RETURN VALUE" +The +\fIfegetround\fR() +function shall return the value of the rounding direction macro +representing the current rounding direction or a negative value if +there is no such rounding direction macro or the current rounding +direction is not determinable. +.P +The +\fIfesetround\fR() +function shall return a zero value if and only if the requested +rounding direction was established. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example saves, sets, and restores the rounding direction, +reporting an error and aborting if setting the rounding direction +fails: +.sp +.RS 4 +.nf + +#include +#include +void f(int round_dir) +{ + #pragma STDC FENV_ACCESS ON + int save_round; + int setround_ok; + save_round = fegetround(); + setround_ok = fesetround(round_dir); + assert(setround_ok == 0); + /* ... */ + fesetround(save_round); + /* ... */ +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/feholdexcept.3p b/upstream/archlinux/man3p/feholdexcept.3p new file mode 100644 index 00000000..a968c8d6 --- /dev/null +++ b/upstream/archlinux/man3p/feholdexcept.3p @@ -0,0 +1,78 @@ +'\" et +.TH FEHOLDEXCEPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +feholdexcept +\(em save current floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int feholdexcept(fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfeholdexcept\fR() +function shall save the current floating-point environment in the +object pointed to by +.IR envp , +clear the floating-point status flags, and then install a non-stop +(continue on floating-point exceptions) mode, if available, for all +floating-point exceptions. +.SH "RETURN VALUE" +The +\fIfeholdexcept\fR() +function shall return zero if and only if non-stop floating-point +exception handling was successfully installed. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIfeholdexcept\fR() +function should be effective on typical IEC\ 60559:\|1989 standard implementations which +have the default non-stop mode and at least one other mode for trap +handling or aborting. If the implementation provides only the non-stop +mode, then installing the non-stop mode is trivial. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfegetenv\fR\^(\|)", +.IR "\fIfeupdateenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/feof.3p b/upstream/archlinux/man3p/feof.3p new file mode 100644 index 00000000..96394fa3 --- /dev/null +++ b/upstream/archlinux/man3p/feof.3p @@ -0,0 +1,80 @@ +'\" et +.TH FEOF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +feof +\(em test end-of-file indicator on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int feof(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfeof\fR() +function shall test the end-of-file indicator for the stream pointed +to by +.IR stream . +.P +The +\fIfeof\fR() +function shall not change the setting of +.IR errno +if +.IR stream +is valid. +.SH "RETURN VALUE" +The +\fIfeof\fR() +function shall return non-zero if and only if the end-of-file +indicator is set for +.IR stream . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclearerr\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/feraiseexcept.3p b/upstream/archlinux/man3p/feraiseexcept.3p new file mode 100644 index 00000000..661f5dfe --- /dev/null +++ b/upstream/archlinux/man3p/feraiseexcept.3p @@ -0,0 +1,91 @@ +'\" et +.TH FERAISEEXCEPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +feraiseexcept +\(em raise floating-point exception +.SH SYNOPSIS +.LP +.nf +#include +.P +int feraiseexcept(int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIferaiseexcept\fR() +function shall attempt to raise the supported floating-point exceptions +represented by the +.IR excepts +argument. The order in which these floating-point exceptions are raised is +unspecified, +except that if the +.IR excepts +argument represents IEC 60559 valid coincident floating-point +exceptions for atomic operations (namely overflow and inexact, +or underflow and inexact), then overflow or underflow shall be +raised before inexact. +Whether the +\fIferaiseexcept\fR() +function additionally raises the inexact floating-point exception +whenever it raises the overflow or underflow floating-point exception +is implementation-defined. +.SH "RETURN VALUE" +If the argument is zero or if all the specified exceptions were +successfully raised, +\fIferaiseexcept\fR() +shall return zero. Otherwise, it shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The effect is intended to be similar to that of floating-point +exceptions raised by arithmetic operations. Hence, enabled traps for +floating-point exceptions raised by this function are taken. +.SH RATIONALE +Raising overflow or underflow is allowed to also raise inexact because +on some architectures the only practical way to raise an exception is +to execute an instruction that has the exception as a side-effect. The +function is not restricted to accept only valid coincident expressions +for atomic operations, so the function can be used to raise exceptions +accrued over several operations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ferror.3p b/upstream/archlinux/man3p/ferror.3p new file mode 100644 index 00000000..bf7630a3 --- /dev/null +++ b/upstream/archlinux/man3p/ferror.3p @@ -0,0 +1,79 @@ +'\" et +.TH FERROR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ferror +\(em test error indicator on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int ferror(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIferror\fR() +function shall test the error indicator for the stream pointed to by +.IR stream . +.P +The +\fIferror\fR() +function shall not change the setting of +.IR errno +if +.IR stream +is valid. +.SH "RETURN VALUE" +The +\fIferror\fR() +function shall return non-zero if and only if the error indicator is +set for +.IR stream . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclearerr\fR\^(\|)", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fesetenv.3p b/upstream/archlinux/man3p/fesetenv.3p new file mode 100644 index 00000000..69f15a95 --- /dev/null +++ b/upstream/archlinux/man3p/fesetenv.3p @@ -0,0 +1,40 @@ +'\" et +.TH FESETENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fesetenv +\(em set current floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int fesetenv(const fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfegetenv\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fesetexceptflag.3p b/upstream/archlinux/man3p/fesetexceptflag.3p new file mode 100644 index 00000000..6302ccb3 --- /dev/null +++ b/upstream/archlinux/man3p/fesetexceptflag.3p @@ -0,0 +1,40 @@ +'\" et +.TH FESETEXCEPTFLAG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fesetexceptflag +\(em set floating-point status flags +.SH SYNOPSIS +.LP +.nf +#include +.P +int fesetexceptflag(const fexcept_t *\fIflagp\fP, int \fIexcepts\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfegetexceptflag\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fesetround.3p b/upstream/archlinux/man3p/fesetround.3p new file mode 100644 index 00000000..f3e123e1 --- /dev/null +++ b/upstream/archlinux/man3p/fesetround.3p @@ -0,0 +1,40 @@ +'\" et +.TH FESETROUND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fesetround +\(em set current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +int fesetround(int \fIround\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfegetround\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fetestexcept.3p b/upstream/archlinux/man3p/fetestexcept.3p new file mode 100644 index 00000000..34b2e3e0 --- /dev/null +++ b/upstream/archlinux/man3p/fetestexcept.3p @@ -0,0 +1,97 @@ +'\" et +.TH FETESTEXCEPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fetestexcept +\(em test floating-point exception flags +.SH SYNOPSIS +.LP +.nf +#include +.P +int fetestexcept(int \fIexcepts\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfetestexcept\fR() +function shall determine which of a specified subset of the +floating-point exception flags are currently set. The +.IR excepts +argument specifies the floating-point status flags to be queried. +.SH "RETURN VALUE" +The +\fIfetestexcept\fR() +function shall return the value of the bitwise-inclusive OR of the +floating-point exception macros corresponding to the currently set +floating-point exceptions included in +.IR excepts . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example calls function +\fIf\fR() +if an invalid exception is set, and then function +\fIg\fR() +if an overflow exception is set: +.sp +.RS 4 +.nf + +#include +/* ... */ +{ + #pragma STDC FENV_ACCESS ON + int set_excepts; + feclearexcept(FE_INVALID | FE_OVERFLOW); + // maybe raise exceptions + set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW); + if (set_excepts & FE_INVALID) f(); + if (set_excepts & FE_OVERFLOW) g(); + /* ... */ +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfegetexceptflag\fR\^(\|)", +.IR "\fIferaiseexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/feupdateenv.3p b/upstream/archlinux/man3p/feupdateenv.3p new file mode 100644 index 00000000..0174043d --- /dev/null +++ b/upstream/archlinux/man3p/feupdateenv.3p @@ -0,0 +1,100 @@ +'\" et +.TH FEUPDATEENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +feupdateenv +\(em update floating-point environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int feupdateenv(const fenv_t *\fIenvp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfeupdateenv\fR() +function shall attempt to save the currently raised floating-point +exceptions in its automatic storage, attempt to install the +floating-point environment represented by the object pointed to by +.IR envp , +and then attempt to raise the saved floating-point exceptions. The +argument +.IR envp +shall point to an object set by a call to +\fIfeholdexcept\fR() +or +\fIfegetenv\fR(), +or equal a floating-point environment macro. +.SH "RETURN VALUE" +The +\fIfeupdateenv\fR() +function shall return a zero value if and only if all the required +actions were successfully carried out. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example shows sample code to hide spurious underflow +floating-point exceptions: +.sp +.RS 4 +.nf + +#include +double f(double x) +{ + #pragma STDC FENV_ACCESS ON + double result; + fenv_t save_env; + feholdexcept(&save_env); + // compute result + if (/* test spurious underflow */) + feclearexcept(FE_UNDERFLOW); + feupdateenv(&save_env); + return result; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfegetenv\fR\^(\|)", +.IR "\fIfeholdexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fexecve.3p b/upstream/archlinux/man3p/fexecve.3p new file mode 100644 index 00000000..e2dec977 --- /dev/null +++ b/upstream/archlinux/man3p/fexecve.3p @@ -0,0 +1,39 @@ +'\" et +.TH FEXECVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fexecve \(em execute a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fexecve(int \fIfd\fP, char *const \fIargv[]\fP, char *const \fIenvp[]\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIexec\fR\^". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fflush.3p b/upstream/archlinux/man3p/fflush.3p new file mode 100644 index 00000000..1e680daa --- /dev/null +++ b/upstream/archlinux/man3p/fflush.3p @@ -0,0 +1,217 @@ +'\" et +.TH FFLUSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fflush +\(em flush a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fflush(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR stream +points to an output stream or an update stream in which the most recent +operation was not input, +\fIfflush\fR() +shall cause any unwritten data for that stream to be written to the +file, +and the last data modification and last file status change timestamps +of the underlying file shall be marked for update. +.P +For a stream open for reading with an underlying file description, +if the file is not already at EOF, and the file is one capable +of seeking, the file offset of the underlying open file description +shall be set to the file position of the stream, and any characters +pushed back onto the stream by +\fIungetc\fR() +or +\fIungetwc\fR() +that have not subsequently been read from the stream shall be discarded +(without further changing the file offset). +.P +If +.IR stream +is a null pointer, +\fIfflush\fR() +shall perform this flushing action on all streams for which the +behavior is defined above. +.SH "RETURN VALUE" +Upon successful completion, +\fIfflush\fR() +shall return 0; otherwise, it shall set the error indicator for +the stream, return EOF, +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfflush\fR() +function shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not valid. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The +\fIfflush\fR() +function was interrupted by a signal. +.TP +.BR EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the calling thread +is not blocking SIGTTOU, the process is not ignoring SIGTTOU, and the +process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOMEM +The underlying stream was created by +\fIopen_memstream\fR() +or +\fIopen_wmemstream\fR() +and insufficient memory is available. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file or +in the buffer used by the +\fIfmemopen\fR() +function. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the thread. +.P +The +\fIfflush\fR() +function may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was +outside the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending Prompts to Standard Output" +.P +The following example uses +\fIprintf\fR() +calls to print a series of prompts for information the user must enter +from standard input. The +\fIfflush\fR() +calls force the output to standard output. The +\fIfflush\fR() +function is used because standard output is usually buffered and the +prompt may not immediately be printed on the output or terminal. The +\fIgetline\fR() +function calls read strings from standard input and place the +results in variables, for use later in the program. +.sp +.RS 4 +.nf + +char *user; +char *oldpasswd; +char *newpasswd; +ssize_t llen; +size_t blen; +struct termios term; +tcflag_t saveflag; +.P +printf("User name: "); +fflush(stdout); +blen = 0; +llen = getline(&user, &blen, stdin); +user[llen-1] = 0; +tcgetattr(fileno(stdin), &term); +saveflag = term.c_lflag; +term.c_lflag &= \(tiECHO; +tcsetattr(fileno(stdin), TCSANOW, &term); +printf("Old password: "); +fflush(stdout); +blen = 0; +llen = getline(&oldpasswd, &blen, stdin); +oldpasswd[llen-1] = 0; +.P +printf("\enNew password: "); +fflush(stdout); +blen = 0; +llen = getline(&newpasswd, &blen, stdin); +newpasswd[llen-1] = 0; +term.c_lflag = saveflag; +tcsetattr(fileno(stdin), TCSANOW, &term); +free(user); +free(oldpasswd); +free(newpasswd); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Data buffered by the system may make determining the validity of the +position of the current file descriptor impractical. Thus, enforcing +the repositioning of the file descriptor after +\fIfflush\fR() +on streams open for +\fIread\fR() +is not mandated by POSIX.1\(hy2008. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ffs.3p b/upstream/archlinux/man3p/ffs.3p new file mode 100644 index 00000000..a6634e42 --- /dev/null +++ b/upstream/archlinux/man3p/ffs.3p @@ -0,0 +1,68 @@ +'\" et +.TH FFS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ffs +\(em find first set bit +.SH SYNOPSIS +.LP +.nf +#include +.P +int ffs(int \fIi\fP); +.fi +.SH DESCRIPTION +The +\fIffs\fR() +function shall find the first bit set (beginning with the least +significant bit) in +.IR i , +and return the index of that bit. Bits are numbered starting at one +(the least significant bit). +.SH "RETURN VALUE" +The +\fIffs\fR() +function shall return the index of the first bit set. If +.IR i +is 0, then +\fIffs\fR() +shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fgetc.3p b/upstream/archlinux/man3p/fgetc.3p new file mode 100644 index 00000000..63075c27 --- /dev/null +++ b/upstream/archlinux/man3p/fgetc.3p @@ -0,0 +1,177 @@ +'\" et +.TH FGETC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fgetc +\(em get a byte from a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fgetc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If the end-of-file indicator for the input stream pointed to by +.IR stream +is not set and a next byte is present, the +\fIfgetc\fR() +function shall obtain the next byte as an +.BR "unsigned char" +converted to an +.BR int , +from the input stream pointed to by +.IR stream , +and advance the associated file position indicator for the stream (if +defined). Since +\fIfgetc\fR() +operates on bytes, reading a character consisting of multiple bytes (or +``a multi-byte character'') may require multiple calls to +\fIfgetc\fR(). +.P +The +\fIfgetc\fR() +function may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be marked for +update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfgetc\fR() +shall return the next byte from the input stream pointed to by +.IR stream . +If the end-of-file indicator for the stream is set, or if the +stream is at end-of-file, the end-of-file indicator for the +stream shall be set and +\fIfgetc\fR() +shall return EOF. If a read error occurs, the error indicator for the +stream shall be set, +\fIfgetc\fR() +shall return EOF, +and shall set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfgetc\fR() +function shall fail if data needs to be read and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the +\fIfgetc\fR() +operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for reading. +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is in a background +process group attempting to read from its controlling terminal, and +either the calling thread is blocking SIGTTIN or the process is ignoring +SIGTTIN or the process group of the process is orphaned. +This error may also be generated for implementation-defined reasons. +.TP +.BR EOVERFLOW +The file is a regular file and an attempt was made to read at or beyond +the offset maximum associated with the corresponding stream. +.P +The +\fIfgetc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the integer value returned by +\fIfgetc\fR() +is stored into a variable of type +.BR char +and then compared against the integer constant EOF, the comparison may +never succeed, because sign-extension of a variable of type +.BR char +on widening to integer is implementation-defined. +.P +The +\fIferror\fR() +or +\fIfeof\fR() +functions must be used to distinguish between an error condition and an +end-of-file condition. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fgetpos.3p b/upstream/archlinux/man3p/fgetpos.3p new file mode 100644 index 00000000..383792d1 --- /dev/null +++ b/upstream/archlinux/man3p/fgetpos.3p @@ -0,0 +1,103 @@ +'\" et +.TH FGETPOS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fgetpos +\(em get current file position information +.SH SYNOPSIS +.LP +.nf +#include +.P +int fgetpos(FILE *restrict \fIstream\fP, fpos_t *restrict \fIpos\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfgetpos\fR() +function shall store the current values of the parse state (if any) +and file position indicator for the stream pointed to by +.IR stream +in the object pointed to by +.IR pos . +The value stored contains unspecified information usable by +\fIfsetpos\fR() +for repositioning the stream to its position at the time of the call to +\fIfgetpos\fR(). +.P +The +\fIfgetpos\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, +\fIfgetpos\fR() +shall return 0; otherwise, it shall return a non-zero value and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfgetpos\fR() +function shall fail if: +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not valid. +.TP +.BR EOVERFLOW +The current value of the file position cannot be represented correctly +in an object of type +.BR fpos_t . +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fgets.3p b/upstream/archlinux/man3p/fgets.3p new file mode 100644 index 00000000..cfab9ed0 --- /dev/null +++ b/upstream/archlinux/man3p/fgets.3p @@ -0,0 +1,182 @@ +'\" et +.TH FGETS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fgets +\(em get a string from a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +char *fgets(char *restrict \fIs\fP, int \fIn\fP, FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfgets\fR() +function shall read bytes from +.IR stream +into the array pointed to by +.IR s +until +.IR n \-1 +bytes are read, or a + +is read and transferred to +.IR s , +or an end-of-file condition is encountered. A null byte shall be +written immediately after the last byte read into the array. +If the end-of-file condition is encountered before any bytes +are read, the contents of the array pointed to by +.IR s +shall not be changed. +.P +The +\fIfgets\fR() +function may mark the last data access timestamp of the file associated +with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfgets\fR() +shall return +.IR s . +If the stream is at end-of-file, the end-of-file indicator for +the stream shall be set and +\fIfgets\fR() +shall return a null pointer. +If a read error occurs, the error indicator for the stream shall be set, +\fIfgets\fR() +shall return a null pointer, +and shall set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading Input" +.P +The following example uses +\fIfgets\fR() +to read lines of input. It assumes that the file it is reading is a text +file and that lines in this text file are no longer than 16384 (or +{LINE_MAX} +if it is less than 16384 on the implementation where it is running) +bytes long. (Note that the standard utilities have no line length limit if +.IR sysconf (_SC_LINE_MAX) +returns \-1 without setting +.IR errno . +This example assumes that +.IR sysconf (_SC_LINE_MAX) +will not fail.) +.sp +.RS 4 +.nf + +#include +#include +#include +#define MYLIMIT 16384 +.P +char *line; +int line_max; +if (LINE_MAX >= MYLIMIT) { + // Use maximum line size of MYLIMIT. If LINE_MAX is + // bigger than our limit, sysconf() cannot report a + // smaller limit. + line_max = MYLIMIT; +} else { + long limit = sysconf(_SC_LINE_MAX); + line_max = (limit < 0 || limit > MYLIMIT) ? MYLIMIT : (int)limit; +} +.P +// line_max + 1 leaves room for the null byte added by fgets(). +line = malloc(line_max + 1); +if (line == NULL) { + // out of space + ... + return error; +} +.P +while (fgets(line, line_max + 1, fp) != NULL) { + // Verify that a full line has been read ... + // If not, report an error or prepare to treat the + // next time through the loop as a read of a + // continuation of the current line. + ... + // Process line ... + ... +} +free(line); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIgetdelim\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fgetwc.3p b/upstream/archlinux/man3p/fgetwc.3p new file mode 100644 index 00000000..20462262 --- /dev/null +++ b/upstream/archlinux/man3p/fgetwc.3p @@ -0,0 +1,176 @@ +'\" et +.TH FGETWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fgetwc +\(em get a wide-character code from a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t fgetwc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfgetwc\fR() +function shall obtain the next character (if present) from the input +stream pointed to by +.IR stream , +convert that to the corresponding wide-character code, and advance the +associated file position indicator for the stream (if defined). +.P +If an error occurs, the resulting value of the file position indicator +for the stream is unspecified. +.P +The +\fIfgetwc\fR() +function may mark the last data access timestamp of the file associated +with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetwc\fR(), +\fIfgetws\fR(), +\fIfwscanf\fR(), +\fIgetwc\fR(), +\fIgetwchar\fR(), +\fIvfwscanf\fR(), +\fIvwscanf\fR(), +or +\fIwscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetwc\fR(). +.P +The +\fIfgetwc\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, the +\fIfgetwc\fR() +function shall return the wide-character code of the character read from the +input stream pointed to by +.IR stream +converted to a type +.BR wint_t . +If the end-of-file indicator for the stream is set, or if the stream is +at end-of-file, the end-of-file indicator for the stream shall be set +and +\fIfgetwc\fR() +shall return WEOF. If a read error occurs, the error indicator for the +stream shall be set, +\fIfgetwc\fR() +shall return WEOF, +and shall set +.IR errno +to indicate the error. +If an encoding error occurs, the error indicator for the stream +shall be set, +\fIfgetwc\fR() +shall return WEOF, and shall set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfgetwc\fR() +function shall fail if data needs to be read and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the +\fIfgetwc\fR() +operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for reading. +.TP +.BR EILSEQ +The data obtained from the input stream does not form a valid +character. +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is in a background +process group attempting to read from its controlling terminal, and +either the calling thread is blocking SIGTTIN or the process is ignoring +SIGTTIN or the process group of the process is orphaned. +This error may also be generated for implementation-defined reasons. +.TP +.BR EOVERFLOW +The file is a regular file and an attempt was made to read at or beyond +the offset maximum associated with the corresponding stream. +.br +.P +The +\fIfgetwc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIferror\fR() +or +\fIfeof\fR() +functions must be used to distinguish between an error condition and an +end-of-file condition. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fgetws.3p b/upstream/archlinux/man3p/fgetws.3p new file mode 100644 index 00000000..0d6d01d1 --- /dev/null +++ b/upstream/archlinux/man3p/fgetws.3p @@ -0,0 +1,123 @@ +'\" et +.TH FGETWS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fgetws +\(em get a wide-character string from a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wchar_t *fgetws(wchar_t *restrict \fIws\fP, int \fIn\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfgetws\fR() +function shall read characters from the +.IR stream , +convert these to the corresponding wide-character codes, place them +in the +.BR wchar_t +array pointed to by +.IR ws , +until +.IR n \-1 +characters are read, or a + +is read, converted, and transferred to +.IR ws , +or an end-of-file condition is encountered. The wide-character string, +.IR ws , +shall then be terminated with a null wide-character code. +.P +If an error occurs, the resulting value of the file position indicator +for the stream is unspecified. +.P +The +\fIfgetws\fR() +function may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetwc\fR(), +\fIfgetws\fR(), +\fIfwscanf\fR(), +\fIgetwc\fR(), +\fIgetwchar\fR(), +\fIvfwscanf\fR(), +\fIvwscanf\fR(), +or +\fIwscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetwc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfgetws\fR() +shall return +.IR ws . +If the end-of-file indicator for the stream is set, or if the stream +is at end-of-file, the end-of-file indicator for the +stream shall be set and +\fIfgetws\fR() +shall return a null pointer. If a read error occurs, the error +indicator for the stream shall be set, +\fIfgetws\fR() +shall return a null pointer, +and shall set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fileno.3p b/upstream/archlinux/man3p/fileno.3p new file mode 100644 index 00000000..6e7ba65b --- /dev/null +++ b/upstream/archlinux/man3p/fileno.3p @@ -0,0 +1,96 @@ +'\" et +.TH FILENO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fileno +\(em map a stream pointer to a file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int fileno(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIfileno\fR() +function shall return the integer file descriptor associated with +the stream pointed to by +.IR stream . +.SH "RETURN VALUE" +Upon successful completion, +\fIfileno\fR() +shall return the integer value of the file descriptor associated with +.IR stream . +Otherwise, the value \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfileno\fR() +function shall fail if: +.TP +.BR EBADF +The stream is not associated with a file. +.P +The +\fIfileno\fR() +function may fail if: +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Without some specification of which file descriptors are associated +with these streams, it is impossible for an application to set up the +streams for another application it starts with +\fIfork\fR() +and +.IR exec . +In particular, it would not be possible to write a portable version of +the +.IR sh +command interpreter (although there may be other constraints that would +prevent that portability). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIstdin\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/flockfile.3p b/upstream/archlinux/man3p/flockfile.3p new file mode 100644 index 00000000..64ef6058 --- /dev/null +++ b/upstream/archlinux/man3p/flockfile.3p @@ -0,0 +1,204 @@ +'\" et +.TH FLOCKFILE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +flockfile, +ftrylockfile, +funlockfile +\(em stdio locking functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void flockfile(FILE *\fIfile\fP); +int ftrylockfile(FILE *\fIfile\fP); +void funlockfile(FILE *\fIfile\fP); +.fi +.SH DESCRIPTION +These functions shall provide for explicit application-level locking of +stdio (\c +.BR "FILE *" ) +objects. These functions can be used by a thread to delineate a +sequence of I/O statements that are executed as a unit. +.P +The +\fIflockfile\fR() +function shall acquire for a thread ownership of a (\c +.BR "FILE *" ) +object. +.P +The +\fIftrylockfile\fR() +function shall acquire for a thread ownership of a (\c +.BR "FILE *" ) +object if the object is available; +\fIftrylockfile\fR() +is a non-blocking version of +\fIflockfile\fR(). +.P +The +\fIfunlockfile\fR() +function shall relinquish the ownership granted to the thread. +The behavior is undefined if a thread other than the current owner +calls the +\fIfunlockfile\fR() +function. +.P +The functions shall behave as if there is a lock count associated with +each (\c +.BR "FILE *" ) +object. This count is implicitly initialized to zero when the (\c +.BR "FILE *" ) +object is created. The (\c +.BR "FILE *" ) +object is unlocked when the count is zero. When the count is positive, +a single thread owns the (\c +.BR "FILE *" ) +object. When the +\fIflockfile\fR() +function is called, if the count is zero or if the count is positive +and the caller owns the (\c +.BR "FILE *" ) +object, the count shall be incremented. Otherwise, the calling thread +shall be suspended, waiting for the count to return to zero. Each call +to +\fIfunlockfile\fR() +shall decrement the count. This allows matching calls to +\fIflockfile\fR() +(or successful calls to +\fIftrylockfile\fR()) +and +\fIfunlockfile\fR() +to be nested. +.P +All functions that reference (\c +.BR "FILE *" ) +objects, except those with names ending in +.IR _unlocked , +shall behave as if they use +\fIflockfile\fR() +and +\fIfunlockfile\fR() +internally to obtain ownership of these (\c +.BR "FILE *" ) +objects. +.SH "RETURN VALUE" +None for +\fIflockfile\fR() +and +\fIfunlockfile\fR(). +.P +The +\fIftrylockfile\fR() +function shall return zero for success and non-zero to indicate +that the lock cannot be acquired. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.P +A call to +\fIexit\fR() +can block until locked streams are unlocked because a thread having +ownership of a (\c +.BR FILE *) +object blocks all function calls that reference that (\c +.BR FILE *) +object (except those with names ending in _unlocked) from other threads, +including calls to +\fIexit\fR(). +.SH RATIONALE +The +\fIflockfile\fR() +and +\fIfunlockfile\fR() +functions provide an orthogonal mutual-exclusion lock for each +.BR FILE . +The +\fIftrylockfile\fR() +function provides a non-blocking attempt to acquire a file lock, +analogous to +\fIpthread_mutex_trylock\fR(). +.P +These locks behave as if they are the same as those used internally by +.IR stdio +for thread-safety. +This both provides thread-safety of these functions without requiring a +second level of internal locking and allows functions in +.IR stdio +to be implemented in terms of other +.IR stdio +functions. +.P +Application developers and implementors should be aware that there are +potential deadlock problems on +.BR FILE +objects. For example, the line-buffered flushing semantics of +.IR stdio +(requested via {_IOLBF}) +require that certain input operations sometimes cause the buffered +contents of implementation-defined line-buffered output streams to be +flushed. If two threads each hold the lock on the other's +.BR FILE , +deadlock ensues. This type of deadlock can be avoided by acquiring +.BR FILE +locks in a consistent order. In particular, the line-buffered output +stream deadlock can typically be avoided by acquiring locks on input +streams before locks on output streams if a thread would be acquiring +both. +.P +In summary, threads sharing +.IR stdio +streams with other threads can use +\fIflockfile\fR() +and +\fIfunlockfile\fR() +to cause sequences of I/O performed by a single thread to be kept +bundled. The only case where the use of +\fIflockfile\fR() +and +\fIfunlockfile\fR() +is required is to provide a scope protecting uses of the +.IR *_unlocked +functions/macros. This moves the cost/performance tradeoff to the +optimal point. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexit\fR\^(\|)", +.IR "\fIgetc_unlocked\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/floor.3p b/upstream/archlinux/man3p/floor.3p new file mode 100644 index 00000000..2e75a710 --- /dev/null +++ b/upstream/archlinux/man3p/floor.3p @@ -0,0 +1,99 @@ +'\" et +.TH FLOOR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +floor, +floorf, +floorl +\(em floor function +.SH SYNOPSIS +.LP +.nf +#include +.P +double floor(double \fIx\fP); +float floorf(float \fIx\fP); +long double floorl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the largest integral value not greater +than +.IR x . +.SH "RETURN VALUE" +The result shall have the same sign as +.IR x . +.P +Upon successful completion, these functions shall return the largest +integral value not greater than +.IR x , +expressed as a +.BR double , +.BR float , +or +.BR "long double" , +as appropriate for the return type of the function. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions might not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIceil\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fma.3p b/upstream/archlinux/man3p/fma.3p new file mode 100644 index 00000000..3447930c --- /dev/null +++ b/upstream/archlinux/man3p/fma.3p @@ -0,0 +1,211 @@ +'\" et +.TH FMA "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fma, +fmaf, +fmal +\(em floating-point multiply-add +.SH SYNOPSIS +.LP +.nf +#include +.P +double fma(double \fIx\fP, double \fIy\fP, double \fIz\fP); +float fmaf(float \fIx\fP, float \fIy\fP, float \fIz\fP); +long double fmal(long double \fIx\fP, long double \fIy\fP, long double \fIz\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute (\fIx\fR\ *\ \fIy\fR)\ +\ \fIz\fR, +rounded as one ternary operation: they shall compute the value (as if) +to infinite precision and round once to the result format, according to +the rounding mode characterized by the value of FLT_ROUNDS. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +(\fIx\fR\ *\ \fIy\fR)\ + \fIz\fR, rounded as one ternary operation. +.P +If the result overflows or underflows, a range error may occur. +On systems that support the IEC 60559 Floating-Point option, if the +result overflows a range error shall occur. +.P +If +.IR x +or +.IR y +are NaN, a NaN shall be returned. +.P +If +.IR x +multiplied by +.IR y +is an exact infinity and +.IR z +is also an infinity but with the opposite sign, a domain error shall +occur, and either a NaN (if supported), or an implementation-defined +value shall be returned. +.P +If one of +.IR x +and +.IR y +is infinite, the other is zero, and +.IR z +is not a NaN, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be returned. +.P +If one of +.IR x +and +.IR y +is infinite, the other is zero, and +.IR z +is a NaN, a NaN shall be returned and a domain error may occur. +.P +If +.IR x *\c +.IR y +is not 0*Inf nor Inf*0 and +.IR z +is a NaN, a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x *\c +.IR y +\c +.IR z +is invalid, or the value +.IR x *\c +.IR y +is invalid and +.IR z +is not a NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.br +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The value +.IR x *\c +.IR y +is invalid and +.IR z +is a NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +In many cases, clever use of floating (\fIfused\fR) multiply-add leads +to much improved code; but its unexpected use by the compiler can +undermine carefully written code. The FP_CONTRACT macro can be used to +disallow use of floating multiply-add; and the +\fIfma\fR() +function guarantees its use where desired. Many current machines +provide hardware floating multiply-add instructions; software +implementation can be used for others. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fmax.3p b/upstream/archlinux/man3p/fmax.3p new file mode 100644 index 00000000..c01bd1ac --- /dev/null +++ b/upstream/archlinux/man3p/fmax.3p @@ -0,0 +1,80 @@ +'\" et +.TH FMAX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fmax, +fmaxf, +fmaxl +\(em determine maximum numeric value of two floating-point numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double fmax(double \fIx\fP, double \fIy\fP); +float fmaxf(float \fIx\fP, float \fIy\fP); +long double fmaxl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall determine the maximum numeric value of their +arguments. +NaN arguments shall be treated as missing data: if one argument +is a NaN and the other numeric, then these functions shall +choose the numeric value. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the maximum +numeric value of their arguments. +.P +If just one argument is a NaN, the other argument shall be returned. +.P +If +.IR x +and +.IR y +are NaN, a NaN shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdim\fR\^(\|)", +.IR "\fIfmin\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fmemopen.3p b/upstream/archlinux/man3p/fmemopen.3p new file mode 100644 index 00000000..f98b73c6 --- /dev/null +++ b/upstream/archlinux/man3p/fmemopen.3p @@ -0,0 +1,299 @@ +'\" et +.TH FMEMOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fmemopen +\(em open a memory buffer stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *fmemopen(void *restrict \fIbuf\fP, size_t \fIsize\fP, + const char *restrict \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIfmemopen\fR() +function shall associate the buffer given by the +.IR buf +and +.IR size +arguments with a stream. The +.IR buf +argument shall be either a null pointer or point to a buffer that is at +least +.IR size +bytes long. +.P +The +.IR mode +argument points to a string. If the string is one of the following, +the stream shall be opened in the indicated mode. Otherwise, the behavior +is undefined. +.IP "\fIr\fP" 8 +Open the stream for reading. +.IP "\fIw\fP" 8 +Open the stream for writing. +.IP "\fIa\fP" 8 +Append; open the stream for writing at the first null byte. +.IP "\fIr\fP+" 8 +Open the stream for update (reading and writing). +.IP "\fIw\fP+" 8 +Open the stream for update (reading and writing). Truncate the +buffer contents. +.IP "\fIa\fP+" 8 +Append; open the stream for update (reading and writing); +the initial position is at the first null byte. +.P +Implementations shall accept all mode strings allowed by +\fIfopen\fR(), +but the use of the character +.BR 'b' +shall produce implementation-defined results, where the resulting +.BR "FILE *" +need not behave the same as if +.BR 'b' +were omitted. +.P +If a null pointer is specified as the +.IR buf +argument, +\fIfmemopen\fR() +shall allocate +.IR size +bytes of memory as if by a call to +\fImalloc\fR(). +This buffer shall be automatically freed when the stream is closed. +Because this feature is only useful when the stream is opened for +updating (because there is no way to get a pointer to the buffer) the +\fIfmemopen\fR() +call may fail if the +.IR mode +argument does not include a +.BR '+' . +.P +The stream shall maintain a current position in the buffer. This position +shall be initially set to either the beginning of the buffer (for +.IR r +and +.IR w +modes) or to the first null byte in the buffer (for +.IR a +modes). If no null byte is found in append mode, the initial position +shall be set to one byte after the end of the buffer. +.P +If +.IR buf +is a null pointer, the initial position shall always be set to the +beginning of the buffer. +.P +The stream shall also maintain the size of the current buffer contents; +use of +\fIfseek\fR() +or +\fIfseeko\fR() +on the stream with SEEK_END shall seek relative to this size. For modes +.IR r +and +.IR r+ +the size shall be set to the value given by the +.IR size +argument. For modes +.IR w +and +.IR w+ +the initial size shall be zero and for modes +.IR a +and +.IR a+ +the initial size shall be: +.IP " *" 4 +Zero, if +.IR buf +is a null pointer +.IP " *" 4 +The position of the first null byte in the buffer, if one is found +.IP " *" 4 +The value of the +.IR size +argument, if +.IR buf +is not a null pointer and no null byte is found +.P +A read operation on the stream shall not advance the current buffer +position beyond the current buffer size. Reaching the buffer size in a +read operation shall count as ``end-of-file''. Null bytes in the buffer +shall have no special meaning for reads. The read operation shall start +at the current buffer position of the stream. +.P +A write operation shall start either at the current position of the stream +(if +.IR mode +has not specified +.BR 'a' +as the first character) or at the current size of the stream (if +.IR mode +had +.BR 'a' +as the first character). If the current position at the end of the write +is larger than the current buffer size, the current buffer size shall +be set to the current position. A write operation on the stream shall +not advance the current buffer size beyond the size given in the +.IR size +argument. +.P +When a stream open for writing is flushed or closed, a null byte shall be +written at the current position or at the end of the buffer, depending +on the size of the contents. If a stream open for update is flushed or +closed and the last write has advanced the current buffer size, a null +byte shall be written at the end of the buffer if it fits. +.P +An attempt to seek a memory buffer stream to a negative position or to +a position larger than the buffer size given in the +.IR size +argument shall fail. +.SH "RETURN VALUE" +Upon successful completion, +\fIfmemopen\fR() +shall return a pointer to the object controlling the stream. Otherwise, +a null pointer shall be returned, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfmemopen\fR() +function shall fail if: +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.P +The +\fIfmemopen\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR mode +argument is not valid. +.TP +.BR EINVAL +The +.IR buf +argument is a null pointer and the +.IR mode +argument does not include a +.BR '+' +character. +.TP +.BR EINVAL +The +.IR size +argument specifies a buffer size of zero and the implementation +does not support this. +.TP +.BR ENOMEM +The +.IR buf +argument is a null pointer and the allocation of a buffer of length +.IR size +has failed. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf + +#include +#include +.P +static char buffer[] = "foobar"; +.P +int +main (void) +{ + int ch; + FILE *stream; +.P + stream = fmemopen(buffer, strlen (buffer), "r"); + if (stream == NULL) + /* handle error */; +.P + while ((ch = fgetc(stream)) != EOF) + printf("Got %c\en", ch); +.P + fclose(stream); + return (0); +} +.fi +.P +.RE +.P +This program produces the following output: +.sp +.RS 4 +.nf + +Got f +Got o +Got o +Got b +Got a +Got r +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +This interface has been introduced to eliminate many of the errors +encountered in the construction of strings, notably overflowing of +strings. This interface prevents overflow. +.SH "FUTURE DIRECTIONS" +A future version of this standard may mandate specific behavior when the +.IR mode +argument includes +.BR 'b' . +.P +A future version of this standard may require support of zero-length +buffer streams explicitly. +.SH "SEE ALSO" +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fmin.3p b/upstream/archlinux/man3p/fmin.3p new file mode 100644 index 00000000..7b03b248 --- /dev/null +++ b/upstream/archlinux/man3p/fmin.3p @@ -0,0 +1,80 @@ +'\" et +.TH FMIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fmin, +fminf, +fminl +\(em determine minimum numeric value of two floating-point numbers +.SH SYNOPSIS +.LP +.nf +#include +.P +double fmin(double \fIx\fP, double \fIy\fP); +float fminf(float \fIx\fP, float \fIy\fP); +long double fminl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall determine the minimum numeric value of their +arguments. +NaN arguments shall be treated as missing data: if one argument +is a NaN and the other numeric, then these functions shall +choose the numeric value. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the minimum +numeric value of their arguments. +.P +If just one argument is a NaN, the other argument shall be returned. +.P +If +.IR x +and +.IR y +are NaN, a NaN shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdim\fR\^(\|)", +.IR "\fIfmax\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fmod.3p b/upstream/archlinux/man3p/fmod.3p new file mode 100644 index 00000000..73bd6a6a --- /dev/null +++ b/upstream/archlinux/man3p/fmod.3p @@ -0,0 +1,170 @@ +'\" et +.TH FMOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fmod, +fmodf, +fmodl +\(em floating-point remainder value function +.SH SYNOPSIS +.LP +.nf +#include +.P +double fmod(double \fIx\fP, double \fIy\fP); +float fmodf(float \fIx\fP, float \fIy\fP); +long double fmodl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall return the floating-point remainder of the +division of +.IR x +by +.IR y . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +These functions shall return the value +.IR x \-\c +.IR i *\c +.IR y , +for some integer +.IR i +such that, if +.IR y +is non-zero, the result has the same sign as +.IR x +and magnitude less than the magnitude of +.IR y . +.P +If the correct value would cause underflow, +and is not +representable, +a range error may occur, and +\fIfmod\fR(), +\fImodf\fR(), +and +\fIfmodl\fR() +shall return +0.0, or +(if the IEC 60559 Floating-Point option is not supported) an +implementation-defined value no greater in magnitude than DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned, and none of the conditions +below shall be considered. +.P +If +.IR y +is zero, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is infinite, a domain error shall occur, and a NaN shall be returned. +.P +If +.IR x +is \(+-0 and +.IR y +is not zero, \(+-0 shall be returned. +.P +If +.IR x +is not infinite and +.IR y +is \(+-Inf, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is infinite or +.IR y +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fmtmsg.3p b/upstream/archlinux/man3p/fmtmsg.3p new file mode 100644 index 00000000..3fe4f3b9 --- /dev/null +++ b/upstream/archlinux/man3p/fmtmsg.3p @@ -0,0 +1,249 @@ +'\" et +.TH FMTMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fmtmsg +\(em display a message in the specified format on standard +error and/or a system console +.SH SYNOPSIS +.LP +.nf +#include +.P +int fmtmsg(long \fIclassification\fP, const char *\fIlabel\fP, int \fIseverity\fP, + const char *\fItext\fP, const char *\fIaction\fP, const char *\fItag\fP); +.fi +.SH DESCRIPTION +The +\fIfmtmsg\fR() +function shall display messages in a specified format instead +of the traditional +\fIprintf\fR() +function. +.P +Based on a message's classification component, +\fIfmtmsg\fR() +shall write a formatted message either to standard error, to the +console, or to both. +.P +A formatted message consists of up to five components as defined +below. The component \fIclassification\fR is not part of a message +displayed to the user, but defines the source of the message and +directs the display of the formatted message. +.IP "\fIclassification\fP" 12 +Contains the sum of identifying values constructed from the constants +defined below. Any one identifier from a subclass may be used in +combination with a single identifier from a different subclass. Two or +more identifiers from the same subclass should not be used together, +with the exception of identifiers from the display subclass. (Both +display subclass identifiers may be used so that messages can be +displayed to both standard error and the system console.) +.RS 12 +.IP "\fBMajor Classifications\fP" 6 +.br +Identifies the source of the condition. Identifiers are: MM_HARD +(hardware), MM_SOFT (software), and MM_FIRM (firmware). +.IP "\fBMessage Source Subclassifications\fP" 6 +.br +Identifies the type of software in which the problem is detected. +Identifiers are: MM_APPL (application), MM_UTIL (utility), and MM_OPSYS +(operating system). +.IP "\fBDisplay Subclassifications\fP" 6 +.br +Indicates where the message is to be displayed. Identifiers are: +MM_PRINT to display the message on the standard error stream, +MM_CONSOLE to display the message on the system console. One or both +identifiers may be used. +.IP "\fBStatus Subclassifications\fP" 6 +.br +Indicates whether the application can recover from the condition. +Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV +(non-recoverable). +.P +An additional identifier, MM_NULLMC, indicates that no classification +component is supplied for the message. +.RE +.IP "\fIlabel\fP" 12 +Identifies the source of the message. The format is two fields +separated by a +. +The first field is up to 10 bytes, the second is up to 14 bytes. +.IP "\fIseverity\fP" 12 +Indicates the seriousness of the condition. Identifiers for the levels +of \fIseverity\fR are: +.RS 12 +.IP MM_HALT 12 +Indicates that the application has encountered a severe fault and is +halting. Produces the string +.BR \(dqHALT\(dq . +.IP MM_ERROR 12 +Indicates that the application has detected a fault. Produces the +string +.BR \(dqERROR\(dq . +.IP MM_WARNING 12 +Indicates a condition that is out of the ordinary, that might be a +problem, and should be watched. Produces the string +.BR \(dqWARNING\(dq . +.IP MM_INFO 12 +Provides information about a condition that is not in error. Produces +the string +.BR \(dqINFO\(dq . +.IP MM_NOSEV 12 +Indicates that no severity level is supplied for the message. +.RE +.IP "\fItext\fP" 12 +Describes the error condition that produced the message. The character +string is not limited to a specific size. If the character string is +empty, then the text produced is unspecified. +.IP "\fIaction\fP" 12 +Describes the first step to be taken in the error-recovery process. +The +\fIfmtmsg\fR() +function precedes the action string with the prefix: +.BR \(dqTO FIX:\(dq . +The \fIaction\fR string is not limited to a specific size. +.IP "\fItag\fP" 12 +An identifier that references on-line documentation for the message. +Suggested usage is that \fItag\fR includes the \fIlabel\fR and a unique +identifying number. A sample \fItag\fR is +.BR \(dqXSI:cat:146\(dq . +.P +The +.IR MSGVERB +environment variable (for message verbosity) shall determine for +\fIfmtmsg\fR() +which message components it is to select when writing messages to +standard error. The value of +.IR MSGVERB +shall be a +-separated +list of optional keywords. Valid keywords are: \fIlabel\fR, +\fIseverity\fR, \fItext\fR, \fIaction\fR, and \fItag\fR. If +.IR MSGVERB +contains a keyword for a component and the component's value is not the +component's null value, +\fIfmtmsg\fR() +shall include that component in the message when writing the message to +standard error. If +.IR MSGVERB +does not include a keyword for a message component, that component +shall not be included in the display of the message. The keywords may +appear in any order. If +.IR MSGVERB +is not defined, if its value is the null string, if its value is not of +the correct format, or if it contains keywords other than the valid +ones listed above, +\fIfmtmsg\fR() +shall select all components. +.P +.IR MSGVERB +shall determine which components are selected for display to standard +error. All message components shall be included in console messages. +.SH "RETURN VALUE" +The +\fIfmtmsg\fR() +function shall return one of the following values: +.IP MM_OK 12 +The function succeeded. +.IP MM_NOTOK 12 +The function failed completely. +.IP MM_NOMSG 12 +The function was unable to generate a message on standard error, +but otherwise succeeded. +.IP MM_NOCON 12 +The function was unable to generate a console message, but otherwise +succeeded. +.SH ERRORS +None. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.IP " 1." 4 +The following example of +\fIfmtmsg\fR(): +.RS 4 +.sp +.RS 4 +.nf + +fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option", +"refer to cat in user\(aqs reference manual", "XSI:cat:001") +.fi +.P +.RE +.P +produces a complete message in the specified message format: +.sp +.RS 4 +.nf + +XSI:cat: ERROR: illegal option +TO FIX: refer to cat in user\(aqs reference manual XSI:cat:001 +.fi +.P +.RE +.RE +.IP " 2." 4 +When the environment variable +.IR MSGVERB +is set as follows: +.RS 4 +.sp +.RS 4 +.nf + +MSGVERB=severity:text:action +.fi +.P +.RE +.P +and Example 1 is used, +\fIfmtmsg\fR() +produces: +.sp +.RS 4 +.nf + +ERROR: illegal option +TO FIX: refer to cat in user\(aqs reference manual +.fi +.P +.RE +.RE +.SH "APPLICATION USAGE" +One or more message components may be systematically omitted from +messages generated by an application by using the null value of the +argument for that component. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fnmatch.3p b/upstream/archlinux/man3p/fnmatch.3p new file mode 100644 index 00000000..0cf3a696 --- /dev/null +++ b/upstream/archlinux/man3p/fnmatch.3p @@ -0,0 +1,204 @@ +'\" et +.TH FNMATCH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fnmatch +\(em match a filename string or a pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +int fnmatch(const char *\fIpattern\fP, const char *\fIstring\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIfnmatch\fR() +function shall match patterns as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13.1" ", " "Patterns Matching a Single Character" +and +.IR "Section 2.13.2" ", " "Patterns Matching Multiple Characters". +It checks the string specified by the +.IR string +argument to see if it matches the pattern specified by the +.IR pattern +argument. +.P +The +.IR flags +argument shall modify the interpretation of +.IR pattern +and +.IR string . +It is the bitwise-inclusive OR of zero or more of the flags defined in +.IR . +If the FNM_PATHNAME flag is set in +.IR flags , +then a + +character (\c +.BR '/' ) +in +.IR string +shall be explicitly matched by a + +in +.IR pattern ; +it shall not be matched by either the + +or + +special characters, nor by a bracket expression. If the FNM_PATHNAME flag +is not set, the + +character shall be treated as an ordinary character. +.P +If FNM_NOESCAPE is not set in +.IR flags , +a + +character in +.IR pattern +followed by any other character shall match that second character in +.IR string . +In particular, +.BR \(dq\e\e\(dq +shall match a + +in +.IR string . +If +.IR pattern +ends with an unescaped +, +\fIfnmatch\fR() +shall return a non-zero value (indicating either no match or an error). +If FNM_NOESCAPE is set, a + +character shall be treated as an ordinary character. +.P +If FNM_PERIOD is set in +.IR flags , +then a leading + +(\c +.BR '.' ) +in +.IR string +shall match a + +in +.IR pattern ; +as described by rule 2 in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion" +where the location of ``leading'' is indicated by the value +of FNM_PATHNAME: +.IP " *" 4 +If FNM_PATHNAME is set, a + +is ``leading'' if it is the first character in +.IR string +or if it immediately follows a +. +.IP " *" 4 +If FNM_PATHNAME is not set, a + +is ``leading'' only if it is the first character of +.IR string . +.P +If FNM_PERIOD is not set, then no special restrictions are placed on +matching a period. +.SH "RETURN VALUE" +If +.IR string +matches the pattern specified by +.IR pattern , +then +\fIfnmatch\fR() +shall return 0. If there is no match, +\fIfnmatch\fR() +shall return FNM_NOMATCH, which is defined in +.IR . +If an error occurs, +\fIfnmatch\fR() +shall return another non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfnmatch\fR() +function has two major uses. It could be used by an application or +utility that needs to read a directory and apply a pattern against each +entry. The +.IR find +utility is an example of this. It can also be used by the +.IR pax +utility to process its +.IR pattern +operands, or by applications that need to match strings in a similar +manner. +.P +The name +\fIfnmatch\fR() +is intended to imply +.IR "filename" +match, rather than +.IR "pathname" +match. The default action of this function is to match filename strings, +rather than pathnames, since it gives no special significance to the + +character. With the FNM_PATHNAME flag, +\fIfnmatch\fR() +does match pathnames, but without tilde expansion, parameter +expansion, or special treatment for a + +at the beginning of a filename. +.SH RATIONALE +This function replaced the REG_FILENAME flag of +\fIregcomp\fR() +in early proposals of this volume of POSIX.1\(hy2017. It provides virtually the same functionality +as the +\fIregcomp\fR() +and +\fIregexec\fR() +functions using the REG_FILENAME and REG_FSLASH flags (the REG_FSLASH +flag was proposed for +\fIregcomp\fR(), +and would have had the opposite effect from FNM_PATHNAME), but with a +simpler function and less system overhead. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIglob\fR\^(\|)", +.IR "Section 2.6" ", " "Word Expansions" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fopen.3p b/upstream/archlinux/man3p/fopen.3p new file mode 100644 index 00000000..1ec01c1f --- /dev/null +++ b/upstream/archlinux/man3p/fopen.3p @@ -0,0 +1,358 @@ +'\" et +.TH FOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fopen +\(em open a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *fopen(const char *restrict \fIpathname\fP, const char *restrict \fImode\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfopen\fR() +function shall open the file whose pathname is the string pointed to by +.IR pathname , +and associates a stream with it. +.P +The +.IR mode +argument points to a string. If the string is one of the following, the +file shall be opened in the indicated mode. Otherwise, the behavior is +undefined. +.IP "\fIr\fP\ or\ \fIrb\fP" 14 +Open file for reading. +.IP "\fIw\fP\ or\ \fIwb\fP" 14 +Truncate to zero length or create file for writing. +.IP "\fIa\fP\ or\ \fIab\fP" 14 +Append; open or create file for writing at end-of-file. +.IP "\fIr+\fP\ or\ \fIrb+\fP\ or\ \fIr+b\fP" 14 +Open file for update (reading and writing). +.IP "\fIw+\fP\ or\ \fIwb+\fP\ or\ \fIw+b\fP" 14 +Truncate to zero length or create file for update. +.IP "\fIa+\fP\ or\ \fIab+\fP\ or\ \fIa+b\fP" 14 +Append; open or create file for update, writing at end-of-file. +.P +The character +.BR 'b' +shall have no effect, but is allowed for ISO\ C standard conformance. +Opening a file with read mode (\fIr\fP as the first character in the +.IR mode +argument) shall fail if the file does not exist or cannot be read. +.P +Opening a file with append mode (\fIa\fP as the first character in the +.IR mode +argument) shall cause all subsequent writes to the file to be forced to +the then current end-of-file, regardless of intervening calls to +\fIfseek\fR(). +.P +When a file is opened with update mode (\c +.BR '+' +as the second or third character in the +.IR mode +argument), both input and output may be performed on the associated +stream. However, the application shall ensure that output is not +directly followed by input without an intervening call to +\fIfflush\fR() +or to a file positioning function (\c +\fIfseek\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR()), +and input is not directly followed by output without an intervening +call to a file positioning function, unless the input operation +encounters end-of-file. +.P +When opened, a stream is fully buffered if and only if it can be +determined not to refer to an interactive device. The error and +end-of-file indicators for the stream shall be cleared. +.P +If +.IR mode +is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+, +\fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file +did not previously exist, upon successful completion, +\fIfopen\fR() +shall mark for update the last data access, last data modification, and +last file status change timestamps of the file and the last file status +change and last data modification timestamps of the parent directory. +.P +If +.IR mode +is \fIw\fR, \fIwb\fR, \fIa\fR, \fIab\fR, \fIw\fR+, \fIwb\fR+, +\fIw\fR+\fIb\fR, \fIa\fP+, \fIab\fR+, or \fIa\fR+\fIb\fR, and the file +did not previously exist, the +\fIfopen\fR() +function shall create a file as if it called the +\fIcreat\fR() +function with a value appropriate for the +.IR path +argument interpreted from +.IR pathname +and a value of S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | +S_IWOTH for the +.IR mode +argument. +.P +If +.IR mode +is \fIw\fR, \fIwb\fR, \fIw\fR+, \fIwb\fR+, or \fIw\fR+\fIb\fR, and the +file did previously exist, upon successful completion, +\fIfopen\fR() +shall mark for update the last data modification and last file +status change timestamps of the file. +.P +After a successful call to the +\fIfopen\fR() +function, the orientation of the stream shall be cleared, +the encoding rule shall be cleared, +and the associated +.BR mbstate_t +object shall be set to describe an initial conversion state. +.P +The file descriptor associated with the opened stream shall be allocated +and opened as if by a call to +\fIopen\fR() +with the following flags: +.TS +center box tab(!); +cB | cB +l | l. +\fIfopen\fP(\^) Mode!\fIopen\fP(\^) Flags +_ +\fIr\fR or \fIrb\fR!O_RDONLY +\fIw\fR or \fIwb\fR!O_WRONLY|O_CREAT|O_TRUNC +\fIa\fR or \fIab\fR!O_WRONLY|O_CREAT|O_APPEND +\fIr+\fR or \fIrb+\fR or \fIr+b\fR!O_RDWR +\fIw+\fR or \fIwb+\fR or \fIw+b\fR!O_RDWR|O_CREAT|O_TRUNC +\fIa+\fR or \fIab+\fR or \fIa+b\fR!O_RDWR|O_CREAT|O_APPEND +.TE +.SH "RETURN VALUE" +Upon successful completion, +\fIfopen\fR() +shall return a pointer to the object controlling the stream. Otherwise, +a null pointer shall be returned, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfopen\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or the +file exists and the permissions specified by +.IR mode +are denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created. +.TP +.BR EINTR +A signal was caught during +\fIfopen\fR(). +.TP +.BR EISDIR +The named file is a directory and +.IR mode +requires write access. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOENT +The +.IR mode +string begins with +.BR 'r' +and a component of +.IR pathname +does not name an existing file, or +.IR mode +begins with +.BR 'w' +or +.BR 'a' +and a component of the path prefix of +.IR pathname +does not name an existing file, or +.IR pathname +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR pathname +without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory or file system that would contain the new file cannot be +expanded, the file does not exist, and the file was to be created. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.TP +.BR ENXIO +The named file is a character special or block special file, +and the device associated with this special file does not exist. +.TP +.BR EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.TP +.BR EROFS +The named file resides on a read-only file system and +.IR mode +requires write access. +.P +The +\fIfopen\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR mode +argument is not valid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and +.IR mode +requires write access. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Opening a File" +.P +The following example tries to open the file named +.BR file +for reading. The +\fIfopen\fR() +function returns a file pointer that is used in subsequent +\fIfgets\fR() +and +\fIfclose\fR() +calls. If the program cannot open the file, it just ignores it. +.sp +.RS 4 +.nf + +#include +\&... +FILE *fp; +\&... +void rgrep(const char *file) +{ +\&... + if ((fp = fopen(file, "r")) == NULL) + return; +\&... +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fork.3p b/upstream/archlinux/man3p/fork.3p new file mode 100644 index 00000000..b9758b3d --- /dev/null +++ b/upstream/archlinux/man3p/fork.3p @@ -0,0 +1,433 @@ +'\" et +.TH FORK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fork +\(em create a new process +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t fork(void); +.fi +.SH DESCRIPTION +The +\fIfork\fR() +function shall create a new process. The new process (child process) +shall be an exact copy of the calling process (parent process) except +as detailed below: +.IP " *" 4 +The child process shall have a unique process ID. +.IP " *" 4 +The child process ID also shall not match any active process group ID. +.IP " *" 4 +The child process shall have a different parent process ID, which shall +be the process ID of the calling process. +.IP " *" 4 +The child process shall have its own copy of the parent's file +descriptors. Each of the child's file descriptors shall refer to the +same open file description with the corresponding file descriptor of +the parent. +.IP " *" 4 +The child process shall have its own copy of the parent's open directory +streams. Each open directory stream in the child process may share +directory stream positioning with the corresponding directory stream of +the parent. +.IP " *" 4 +The child process shall have its own copy of the parent's message +catalog descriptors. +.IP " *" 4 +The child process values of +.IR tms_utime , +.IR tms_stime , +.IR tms_cutime , +and +.IR tms_cstime +shall be set to 0. +.IP " *" 4 +The time left until an alarm clock signal shall be reset to zero, and +the alarm, if any, shall be canceled; see +.IR "\fIalarm\fR\^(\|)". +.IP " *" 4 +All +.IR semadj +values shall be cleared. +.IP " *" 4 +File locks set by the parent process shall not be inherited by the +child process. +.IP " *" 4 +The set of signals pending for the child process shall be initialized +to the empty set. +.IP " *" 4 +Interval timers shall be reset in the child process. +.IP " *" 4 +Any semaphores that are open in the parent process shall also be open +in the child process. +.IP " *" 4 +The child process shall not inherit any address space memory locks +established by the parent process via calls to +\fImlockall\fR() +or +\fImlock\fR(). +.IP " *" 4 +Memory mappings created in the parent shall be retained in the child +process. MAP_PRIVATE mappings inherited from the parent shall also be +MAP_PRIVATE mappings in the child, and any modifications to the data in +these mappings made by the parent prior to calling +\fIfork\fR() +shall be visible to the child. Any modifications to the data in +MAP_PRIVATE mappings made by the parent after +\fIfork\fR() +returns shall be visible only to the parent. Modifications to the data +in MAP_PRIVATE mappings made by the child shall be visible only to the +child. +.IP " *" 4 +For the SCHED_FIFO and SCHED_RR scheduling policies, +the child process shall inherit the policy and priority settings of the +parent process during a +\fIfork\fR() +function. For other scheduling policies, the policy and priority +settings on +\fIfork\fR() +are implementation-defined. +.IP " *" 4 +Per-process timers created by the parent shall not be inherited by +the child process. +.IP " *" 4 +The child process shall have its own copy of the message queue +descriptors of the parent. Each of the message descriptors of the child +shall refer to the same open message queue description as the +corresponding message descriptor of the parent. +.IP " *" 4 +No asynchronous input or asynchronous output operations shall be +inherited by the child process. Any use of asynchronous control blocks +created by the parent produces undefined behavior. +.IP " *" 4 +A process shall be created with a single thread. If a multi-threaded +process calls +\fIfork\fR(), +the new process shall contain a replica of the calling thread and its +entire address space, possibly including the states of mutexes and +other resources. Consequently, to avoid errors, the child process may +only execute async-signal-safe operations until such time as one of the +.IR exec +functions is called. +.RS 4 +.P +When the application calls +\fIfork\fR() +from a signal handler and any of the fork handlers registered by +\fIpthread_atfork\fR() +calls a function that is not async-signal-safe, the behavior is +undefined. +.RE +.IP " *" 4 +If the Trace option and the Trace Inherit option are both supported: +.RS 4 +.P +If the calling process was being traced in a trace stream that had its +inheritance policy set to POSIX_TRACE_INHERITED, the child process shall +be traced into that trace stream, and the child process shall inherit +the parent's mapping of trace event names to trace event type +identifiers. If the trace stream in which the calling process was being +traced had its inheritance policy set to POSIX_TRACE_CLOSE_FOR_CHILD, +the child process shall not be traced into that trace stream. The +inheritance policy is set by a call to the +\fIposix_trace_attr_setinherited\fR() +function. +.RE +.IP " *" 4 +If the Trace option is supported, but the Trace Inherit option is not +supported: +.RS 4 +.P +The child process shall not be traced into any of the trace streams +of its parent process. +.RE +.IP " *" 4 +If the Trace option is supported, the child process of a trace +controller process shall not control the trace streams controlled by +its parent process. +.IP " *" 4 +The initial value of the CPU-time clock of the child process shall be +set to zero. +.IP " *" 4 +The initial value of the CPU-time clock of the single thread of the +child process shall be set to zero. +.P +All other process characteristics defined by POSIX.1\(hy2008 shall be the same in +the parent and child processes. The inheritance of process +characteristics not defined by POSIX.1\(hy2008 is unspecified by POSIX.1\(hy2008. +.P +After +\fIfork\fR(), +both the parent and the child processes shall be capable of executing +independently before either one terminates. +.SH "RETURN VALUE" +Upon successful completion, +\fIfork\fR() +shall return 0 to the child process and shall return the process ID +of the child process to the parent process. Both processes shall +continue to execute from the +\fIfork\fR() +function. Otherwise, \-1 shall be +returned to the parent process, no child process shall be created, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfork\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources to create another process, or +the system-imposed limit on the total number of processes under +execution system-wide or by a single user +{CHILD_MAX} +would be exceeded. +.br +.P +The +\fIfork\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Many historical implementations have timing windows where a signal sent +to a process group (for example, an interactive SIGINT) +just prior to or during execution of +\fIfork\fR() +is delivered to the parent following the +\fIfork\fR() +but not to the child because the +\fIfork\fR() +code clears the child's set of pending signals. This volume of POSIX.1\(hy2017 does not require, +or even permit, this behavior. However, it is pragmatic to expect that +problems of this nature may continue to exist in implementations that +appear to conform to this volume of POSIX.1\(hy2017 and pass available verification suites. This +behavior is only a consequence of the implementation failing to make +the interval between signal generation and delivery totally invisible. +From the application's perspective, a +\fIfork\fR() +call should appear atomic. A signal that is generated prior to the +\fIfork\fR() +should be delivered prior to the +\fIfork\fR(). +A signal sent to the process group after the +\fIfork\fR() +should be delivered to both parent and child. The implementation may +actually initialize internal data structures corresponding to the +child's set of pending signals to include signals sent to the process +group during the +\fIfork\fR(). +Since the +\fIfork\fR() +call can be considered as atomic from the application's perspective, +the set would be initialized as empty and such signals would have +arrived after the +\fIfork\fR(); +see also +.IR . +.P +One approach that has been suggested to address the problem of signal +inheritance across +\fIfork\fR() +is to add an +.BR [EINTR] +error, which would be returned when a signal is detected during the +call. While this is preferable to losing signals, it was not +considered an optimal solution. Although it is not recommended for +this purpose, such an error would be an allowable extension for an +implementation. +.P +The +.BR [ENOMEM] +error value is reserved for those implementations that detect and +distinguish such a condition. This condition occurs when an +implementation detects that there is not enough memory to create the +process. This is intended to be returned when +.BR [EAGAIN] +is inappropriate because there can never be enough memory (either +primary or secondary storage) to perform the operation. Since +\fIfork\fR() +duplicates an existing process, this must be a condition where there is +sufficient memory for one such process, but not for two. Many +historical implementations actually return +.BR [ENOMEM] +due to temporary lack of memory, a case that is not generally distinct +from +.BR [EAGAIN] +from the perspective of a conforming application. +.P +Part of the reason for including the optional error +.BR [ENOMEM] +is because the SVID specifies it and it should be reserved for the +error condition specified there. The condition is not applicable on +many implementations. +.P +IEEE\ Std\ 1003.1\(hy1988 neglected to require concurrent execution of the parent and child +of +\fIfork\fR(). +A system that single-threads processes was clearly not intended and is +considered an unacceptable ``toy implementation'' of this volume of POSIX.1\(hy2017. +The only objection anticipated to the phrase ``executing +independently'' is testability, but this assertion should be testable. +Such tests require that both the parent and child can block on a +detectable action of the other, such as a write to a pipe or a signal. +An interactive exchange of such actions should be possible for the +system to conform to the intent of this volume of POSIX.1\(hy2017. +.P +The +.BR [EAGAIN] +error exists to warn applications that such a condition might occur. +Whether it occurs or not is not in any practical sense under the +control of the application because the condition is usually a +consequence of the user's use of the system, not of the application's +code. Thus, no application can or should rely upon its occurrence +under any circumstances, nor should the exact semantics of what concept +of ``user'' is used be of concern to the application developer. +Validation writers should be cognizant of this limitation. +.P +There are two reasons why POSIX programmers call +\fIfork\fR(). +One reason is to create a new thread of control within the same program +(which was originally only possible in POSIX by creating a new +process); the other is to create a new process running a different +program. In the latter case, the call to +\fIfork\fR() +is soon followed by a call to one of the +.IR exec +functions. +.P +The general problem with making +\fIfork\fR() +work in a multi-threaded world is what to do with all of the threads. +There are two alternatives. One is to copy all of the threads into the +new process. This causes the programmer or implementation to deal with +threads that are suspended on system calls or that might be about to +execute system calls that should not be executed in the new process. +The other alternative is to copy only the thread that calls +\fIfork\fR(). +This creates the difficulty that the state of process-local resources +is usually held in process memory. If a thread that is not calling +\fIfork\fR() +holds a resource, that resource is never released in the child process +because the thread whose job it is to release the resource does not +exist in the child process. +.P +When a programmer is writing a multi-threaded program, the first +described use of +\fIfork\fR(), +creating new threads in the same program, is provided by the +\fIpthread_create\fR() +function. The +\fIfork\fR() +function is thus used only to run new programs, and the effects of +calling functions that require certain resources between the call to +\fIfork\fR() +and the call to an +.IR exec +function are undefined. +.P +The addition of the +\fIforkall\fR() +function to the standard was considered and rejected. The +\fIforkall\fR() +function lets all the threads in the parent be duplicated in the +child. This essentially duplicates the state of the parent in the +child. This allows threads in the child to continue processing and +allows locks and the state to be preserved without explicit +\fIpthread_atfork\fR() +code. The calling process has to ensure that the threads processing +state that is shared between the parent and child (that is, file +descriptors or MAP_SHARED +memory) behaves properly after +\fIforkall\fR(). +For example, if a thread is reading a file descriptor in the parent +when +\fIforkall\fR() +is called, then two threads (one in the parent and one in the child) +are reading the file descriptor after the +\fIforkall\fR(). +If this is not desired behavior, the parent process has to synchronize +with such threads before calling +\fIforkall\fR(). +.P +While the +\fIfork\fR() +function is async-signal-safe, there is no way for an implementation to +determine whether the fork handlers established by +\fIpthread_atfork\fR() +are async-signal-safe. The fork handlers may attempt to execute +portions of the implementation that are not async-signal-safe, such as +those that are protected by mutexes, leading to a deadlock condition. +It is therefore undefined for the fork handlers to execute functions +that are not async-signal-safe when +\fIfork\fR() +is called from a signal handler. +.P +When +\fIforkall\fR() +is called, threads, other than the calling thread, that are in +functions that can return with an +.BR [EINTR] +error may have those functions return +.BR [EINTR] +if the implementation cannot ensure that the function behaves correctly +in the parent and child. In particular, +\fIpthread_cond_wait\fR() +and +\fIpthread_cond_timedwait\fR() +need to return in order to ensure that the condition has not changed. +These functions can be awakened by a spurious condition wakeup rather +than returning +.BR [EINTR] . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fItimes\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fpathconf.3p b/upstream/archlinux/man3p/fpathconf.3p new file mode 100644 index 00000000..d9bbc0c1 --- /dev/null +++ b/upstream/archlinux/man3p/fpathconf.3p @@ -0,0 +1,514 @@ +'\" et +.TH FPATHCONF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fpathconf, +pathconf +\(em get configurable pathname variables +.SH SYNOPSIS +.LP +.nf +#include +.P +long fpathconf(int \fIfildes\fP, int \fIname\fP); +long pathconf(const char *\fIpath\fP, int \fIname\fP); +.fi +.SH DESCRIPTION +The +\fIfpathconf\fR() +and +\fIpathconf\fR() +functions shall determine the current value of a configurable limit or +option (\fIvariable\fP) that is associated with a file or directory. +.P +For +\fIpathconf\fR(), +the +.IR path +argument points to the pathname of a file or directory. +.P +For +\fIfpathconf\fR(), +the +.IR fildes +argument is an open file descriptor. +.P +The +.IR name +argument represents the variable to be queried relative to that file or +directory. Implementations shall support all of the variables listed in +the following table and may support others. The variables in the +following table come from +.IR +or +.IR +and the symbolic constants, defined in +.IR , +are the corresponding values used for +.IR name . +.TS +center box tab(!); +cB | cB | cB +l | l | l. +Variable!Value of \fIname\fP!Requirements +_ +{FILESIZEBITS}!_PC_FILESIZEBITS!4,\|7 +{LINK_MAX}!_PC_LINK_MAX!1 +{MAX_CANON}!_PC_MAX_CANON!2 +{MAX_INPUT}!_PC_MAX_INPUT!2 +{NAME_MAX}!_PC_NAME_MAX!3,\|4 +{PATH_MAX}!_PC_PATH_MAX!4,\|5 +{PIPE_BUF}!_PC_PIPE_BUF!6 +{POSIX2_SYMLINKS}!_PC_2_SYMLINKS!4 +{POSIX_ALLOC_SIZE_MIN}!_PC_ALLOC_SIZE_MIN!10 +{POSIX_REC_INCR_XFER_SIZE}!_PC_REC_INCR_XFER_SIZE!10 +{POSIX_REC_MAX_XFER_SIZE}!_PC_REC_MAX_XFER_SIZE!10 +{POSIX_REC_MIN_XFER_SIZE}!_PC_REC_MIN_XFER_SIZE!10 +{POSIX_REC_XFER_ALIGN}!_PC_REC_XFER_ALIGN!10 +{SYMLINK_MAX}!_PC_SYMLINK_MAX!4,\|9 +_POSIX_CHOWN_RESTRICTED!_PC_CHOWN_RESTRICTED!7 +_POSIX_NO_TRUNC!_PC_NO_TRUNC!3,\|4 +_POSIX_VDISABLE!_PC_VDISABLE!2 +_POSIX_ASYNC_IO!_PC_ASYNC_IO!8 +_POSIX_PRIO_IO!_PC_PRIO_IO!8 +_POSIX_SYNC_IO!_PC_SYNC_IO!8 +_POSIX_TIMESTAMP_RESOLUTION!_PC_TIMESTAMP_RESOLUTION!1 +.TE +.SS "Requirements" +.IP " 1." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to the directory +itself. +.IP " 2." 4 +If +.IR path +or +.IR fildes +does not refer to a terminal file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.IP " 3." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to filenames +within the directory. +.IP " 4." 4 +If +.IR path +or +.IR fildes +does not refer to a directory, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.IP " 5." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall be the maximum length +of a relative pathname that would not cross any mount points when the +specified directory is the working directory. +.IP " 6." 4 +If +.IR path +refers to a FIFO, or +.IR fildes +refers to a pipe or FIFO, the value returned shall apply to the +referenced object. If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to any FIFO that +exists or can be created within the directory. If +.IR path +or +.IR fildes +refers to any other type of file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. +.IP " 7." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall apply to any files, +other than directories, that exist or can be created within the +directory. +.IP " 8." 4 +If +.IR path +or +.IR fildes +refers to a directory, it is unspecified whether an implementation +supports an association of the variable name with the specified file. +.IP " 9." 4 +If +.IR path +or +.IR fildes +refers to a directory, the value returned shall be the maximum length +of the string that a symbolic link in that directory can contain. +.IP 10. 4 +If +.IR path +or +.IR fildes +des does not refer to a regular file, it is unspecified whether an +implementation supports an association of the variable name with the +specified file. If an implementation supports such an association for +other than a regular file, the value returned is unspecified. +.SH "RETURN VALUE" +If +.IR name +is an invalid value, both +\fIpathconf\fR() +and +\fIfpathconf\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.P +If the variable corresponding to +.IR name +is described in +.IR +as a maximum or minimum value and the variable has no limit for the +path or file descriptor, both +\fIpathconf\fR() +and +\fIfpathconf\fR() +shall return \-1 without changing +.IR errno . +Note that indefinite limits do not imply infinite limits; see +.IR . +.P +If the implementation needs to use +.IR path +to determine the value of +.IR name +and the implementation does not support the association of +.IR name +with the file specified by +.IR path , +or if the process did not have appropriate privileges to query the +file specified by +.IR path , +or +.IR path +does not exist, +\fIpathconf\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.P +If the implementation needs to use +.IR fildes +to determine the value of +.IR name +and the implementation does not support the association of +.IR name +with the file specified by +.IR fildes , +or if +.IR fildes +is an invalid file descriptor, +\fIfpathconf\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.P +Otherwise, +\fIpathconf\fR() +or +\fIfpathconf\fR() +shall return the current variable value for the file or directory +without changing +.IR errno . +The value returned shall not be more restrictive than the corresponding +value available to the application when it was compiled with the +implementation's +.IR +or +.IR . +.P +If the variable corresponding to +.IR name +is dependent on an unsupported option, the results are unspecified. +.SH ERRORS +The +\fIpathconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR name +is not valid. +.TP +.BR EOVERFLOW +The value of +.IR name +is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than +{LONG_MAX}. +.br +.P +The +\fIpathconf\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix. +.TP +.BR EINVAL +The implementation does not support an association of the variable +.IR name +with the specified file. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.P +The +\fIfpathconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR name +is not valid. +.TP +.BR EOVERFLOW +The value of +.IR name +is _PC_TIMESTAMP_RESOLUTION and the resolution is larger than +{LONG_MAX}. +.P +The +\fIfpathconf\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The implementation does not support an association of the variable +.IR name +with the specified file. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Application developers should check whether an option, such as +_POSIX_ADVISORY_INFO, is supported prior to obtaining and using values +for related variables such as +{POSIX_ALLOC_SIZE_MIN}. +.SH RATIONALE +The +\fIpathconf\fR() +function was proposed immediately after the +\fIsysconf\fR() +function when it was realized that some configurable values may differ +across file system, directory, or device boundaries. +.P +For example, +{NAME_MAX} +frequently changes between System V and +BSD-based file systems; System V uses a maximum of 14, BSD 255. On an +implementation that provides both types of file systems, an application +would be forced to limit all pathname components to 14 bytes, as this +would be the value specified in +.IR +on such a system. +.P +Therefore, various useful values can be queried on any pathname or file +descriptor, assuming that appropriate privileges +are in place. +.P +The value returned for the variable +{PATH_MAX} +indicates the longest relative pathname that could be given if the +specified directory is the current working directory of the process. A +process may not always be able to generate a name that long and use it +if a subdirectory in the pathname crosses into a more restrictive file +system. Note that implementations are allowed to accept pathnames +longer than +{PATH_MAX} +bytes long, but are not allowed to return pathnames longer than this +unless the user specifies a larger buffer using a function that provides +a buffer size argument. +.P +The value returned for the variable _POSIX_CHOWN_RESTRICTED +also applies to directories that do not have file systems mounted on +them. The value may change when crossing a mount point, so +applications that need to know should check for each directory. (An +even easier check is to try the +\fIchown\fR() +function and look for an error in case it happens.) +.P +Unlike the values returned by +\fIsysconf\fR(), +the pathname-oriented variables are potentially more volatile and are +not guaranteed to remain constant throughout the lifetime of the process. +For example, in between two calls to +\fIpathconf\fR(), +the file system in question may have been unmounted and remounted with +different characteristics. +.P +Also note that most of the errors are optional. If one of the +variables always has the same value on an implementation, the +implementation need not look at +.IR path +or +.IR fildes +to return that value and is, therefore, not required to detect +any of the errors except the meaning of +.BR [EINVAL] +that indicates that the value of +.IR name +is not valid for that variable, and the +.BR [EOVERFLOW] +error that indicates the value to be returned is larger than +{LONG_MAX}. +.P +If the value of any of the limits is unspecified (logically +infinite), they will not be defined in +.IR +and the +\fIpathconf\fR() +and +\fIfpathconf\fR() +functions return \-1 without changing +.IR errno . +This can be distinguished from the case of giving an unrecognized +.IR name +argument because +.IR errno +is set to +.BR [EINVAL] +in this case. +.P +Since \-1 is a valid return value for the +\fIpathconf\fR() +and +\fIfpathconf\fR() +functions, applications should set +.IR errno +to zero before calling them and check +.IR errno +only if the return value is \-1. +.P +For the case of +{SYMLINK_MAX}, +since both +\fIpathconf\fR() +and +\fIopen\fR() +follow symbolic links, there is no way that +.IR path +or +.IR fildes +could refer to a symbolic link. +.P +It was the intention of IEEE\ Std 1003.1d\(hy1999 that the following variables: +.sp +.RS +{POSIX_ALLOC_SIZE_MIN} +{POSIX_REC_INCR_XFER_SIZE} +{POSIX_REC_MAX_XFER_SIZE} +{POSIX_REC_MIN_XFER_SIZE} +{POSIX_REC_XFER_ALIGN} +.RE +.P +only applied to regular files, but Note 10 also permits implementation +of the advisory semantics on other file types unique to an +implementation (for example, a character special device). +.P +The +.BR [EOVERFLOW] +error for _PC_TIMESTAMP_RESOLUTION cannot occur on POSIX-compliant +file systems because POSIX requires a timestamp resolution no +larger than one second. Even on 32-bit systems, this can be +represented without overflow. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchown\fR\^(\|)", +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIgetconf\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fpclassify.3p b/upstream/archlinux/man3p/fpclassify.3p new file mode 100644 index 00000000..79c69590 --- /dev/null +++ b/upstream/archlinux/man3p/fpclassify.3p @@ -0,0 +1,75 @@ +'\" et +.TH FPCLASSIFY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fpclassify +\(em classify real floating type +.SH SYNOPSIS +.LP +.nf +#include +.P +int fpclassify(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfpclassify\fR() +macro shall classify its argument value as NaN, infinite, normal, +subnormal, zero, or into another implementation-defined category. +First, an argument represented in a format wider than its semantic type +is converted to its semantic type. Then classification is based on the +type of the argument. +.SH "RETURN VALUE" +The +\fIfpclassify\fR() +macro shall return the value of the number classification macro +appropriate to the value of its argument. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fprintf.3p b/upstream/archlinux/man3p/fprintf.3p new file mode 100644 index 00000000..185e2738 --- /dev/null +++ b/upstream/archlinux/man3p/fprintf.3p @@ -0,0 +1,1491 @@ +'\" et +.TH FPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +dprintf, +fprintf, +printf, +snprintf, +sprintf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int dprintf(int \fIfildes\fP, const char *restrict \fIformat\fP, ...); +int fprintf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, ...); +int printf(const char *restrict \fIformat\fP, ...); +int snprintf(char *restrict \fIs\fP, size_t \fIn\fP, + const char *restrict \fIformat\fP, ...); +int sprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Excluding +\fIdprintf\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfprintf\fR() +function shall place output on the named output +.IR stream . +The +\fIprintf\fR() +function shall place output on the standard output stream +.IR stdout . +The +\fIsprintf\fR() +function shall place output followed by the null byte, +.BR '\e0' , +in consecutive bytes starting at *\fIs\fP; it is the user's +responsibility to ensure that enough space is available. +.P +The +\fIdprintf\fR() +function shall be equivalent to the +\fIfprintf\fR() +function, except that +\fIdprintf\fR() +shall write output to the file associated with the file descriptor +specified by the +.IR fildes +argument rather than place output on a stream. +.P +The +\fIsnprintf\fR() +function shall be equivalent to +\fIsprintf\fR(), +with the addition of the +.IR n +argument which states the size of the buffer referred to by +.IR s . +If +.IR n +is zero, nothing shall be written and +.IR s +may be a null pointer. Otherwise, output bytes beyond the +.IR n \(hy1st +shall be discarded instead of being written to the array, and a null +byte is written at the end of the bytes actually written into the +array. +.P +If copying takes place between objects that overlap as a result of a +call to +\fIsprintf\fR() +or +\fIsnprintf\fR(), +the results are undefined. +.P +Each of these functions converts, formats, and prints its arguments +under control of the +.IR format . +The +.IR format +is a character string, beginning and ending in its initial shift state, +if any. The +.IR format +is composed of zero or more directives: +.IR "ordinary characters" , +which are simply copied to the output stream, and +.IR "conversion specifications" , +each of which shall result in the fetching of zero or more arguments. +The results are undefined if there are insufficient arguments for the +.IR format . +If the +.IR format +is exhausted while arguments remain, the excess arguments shall be +evaluated but are otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier character +.BR % +(see below) is replaced by the sequence \fR"%\fIn\fR$"\fR, where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}], +giving the position of the argument in the argument list. This feature +provides for the definition of format strings that select arguments in +an order appropriate to specific languages (see the EXAMPLES section). +.P +The +.IR format +can contain either numbered argument conversion specifications (that +is, \fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument +conversion specifications (that is, +.BR % +and +.BR * ), +but not both. The only exception to this is that +.BR %% +can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing +numbered and unnumbered argument specifications in a +.IR format +string are undefined. When numbered argument specifications are used, +specifying the +.IR N th +argument requires that all the leading arguments, from the first to the +(\fIN\-1\fP)th, are specified in the format string. +.P +In format strings containing the \fR"%\fIn\fR$"\fR form of conversion +specification, numbered arguments in the argument list can be +referenced from the format string as many times as required. +.P +In format strings containing the +.BR % +form of conversion specification, each conversion specification uses +the first unused argument in the argument list. +.P +All forms of the +\fIfprintf\fR() +functions allow for the insertion of a language-dependent radix +character in the output string. The radix character is defined in the +current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +Each conversion specification is introduced by the +.BR '%' +character +or by the character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +Zero or more +.IR flags +(in any order), which modify the meaning of the conversion +specification. +.IP " *" 4 +An optional minimum +.IR "field width" . +If the converted value has fewer bytes than the field width, it shall +be padded with + +characters by default on the left; it shall be padded on the right if +the left-adjustment flag (\c +.BR '\-' ), +described below, is given to the field width. The field width takes the +form of an + +(\c +.BR '*' ), +described below, or a decimal integer. +.IP " *" 4 +An optional +.IR precision +that gives the minimum number of digits to appear for the +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers; the number of digits to appear after the radix +character for the +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.BR F +conversion specifiers; the maximum number of significant digits for the +.BR g +and +.BR G +conversion specifiers; or the maximum number of bytes to be printed +from a string in the +.BR s +and +.BR S +conversion specifiers. The precision takes the form of a + +(\c +.BR '.' ) +followed either by an + +(\c +.BR '*' ), +described below, or an optional decimal digit string, where a null +digit string is treated as zero. If a precision appears with any other +conversion specifier, the behavior is undefined. +.IP " *" 4 +An optional length modifier that specifies the size of the argument. +.IP " *" 4 +A +.IR "conversion specifier" +character that indicates the type of conversion to be applied. +.P +A field width, or precision, or both, may be indicated by an + +(\c +.BR '*' ). +In this case an argument of type +.BR int +supplies the field width or precision. Applications shall ensure that +arguments specifying field width, or precision, or both appear in that +order before the argument, if any, to be converted. A negative field +width is taken as a +.BR '\-' +flag followed by a positive field width. A negative precision is taken +as if the precision were omitted. +In +.IR format +strings containing the \fR"%\fIn\fR$"\fR form of a +conversion specification, a field width or precision may be indicated +by the sequence \fR"*\fIm\fR$"\fR, where +.IR m +is a decimal integer in the range [1,{NL_ARGMAX}] giving the position +in the argument list (after the +.IR format +argument) of an integer argument containing the field width or +precision, for example: +.sp +.RS 4 +.nf + +printf("%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); +.fi +.P +.RE +.P +The flag characters and their meanings are: +.IP "\fR\(aq\fR" 8 +(The +.) +The integer portion of the result of a decimal conversion (\c +.BR %i , +.BR %d , +.BR %u , +.BR %f , +.BR %F , +.BR %g , +or +.BR %G ) +shall be formatted with thousands' grouping characters. For other +conversions the behavior is undefined. The non-monetary grouping +character is used. +.IP "\fR\-\fR" 8 +The result of the conversion shall be left-justified within the field. +The conversion is right-justified if this flag is not specified. +.IP "\fR+\fR" 8 +The result of a signed conversion shall always begin with a sign (\c +.BR '+' +or +.BR '\-' ). +The conversion shall begin with a sign only when a negative value is +converted if this flag is not specified. +.IP 8 +If the first character of a signed conversion is not a sign or if a +signed conversion results in no characters, a + +shall be prefixed to the result. This means that if the + +and +.BR '+' +flags both appear, the + +flag shall be ignored. +.IP "\fR#\fR" 8 +Specifies that the value is to be converted to an alternative +form. For +.BR o +conversion, it shall increase the precision, if and only if necessary, +to force the first digit of the result to be a zero (if the value +and precision are both 0, a single 0 is printed). For +.BR x +or +.BR X +conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed +to it. For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, the result shall always contain a radix +character, even if no digits follow the radix character. Without this +flag, a radix character appears in the result of these conversions only +if a digit follows it. For +.BR g +and +.BR G +conversion specifiers, trailing zeros shall +.IR not +be removed from the result as they normally are. For other conversion +specifiers, the behavior is undefined. +.IP "\fR0\fR" 8 +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, leading zeros (following any indication of sign +or base) are used to pad to the field width rather than performing +space padding, except when converting an infinity or NaN. If the +.BR '0' +and +.BR '\-' +flags both appear, the +.BR '0' +flag is ignored. For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers, if a precision is specified, the +.BR '0' +flag shall be ignored. +If the +.BR '0' +and + +flags both appear, the grouping characters are inserted before zero +padding. For other conversions, the behavior is undefined. +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "signed char" +or +.BR "unsigned char" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "signed char" +or +.BR "unsigned char" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "signed char" +argument. +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "short" +or +.BR "unsigned short" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "short" +or +.BR "unsigned short" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "short" +argument. +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long" +or +.BR "unsigned long" +argument; that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long" +argument; that a following +.BR c +conversion specifier applies to a +.BR wint_t +argument; that a following +.BR s +conversion specifier applies to a pointer to a +.BR wchar_t +argument; or has no effect on a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier. +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long long" +or +.BR "unsigned long long" +argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long long" +argument. +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to an +.BR intmax_t +or +.BR uintmax_t +argument; or that a following +.BR n +conversion specifier applies to a pointer to an +.BR intmax_t +argument. +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR size_t +or the corresponding signed integer type argument; or that a following +.BR n +conversion specifier applies to a pointer to a signed integer type +corresponding to a +.BR size_t +argument. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR ptrdiff_t +or the corresponding +.BR unsigned +type argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR ptrdiff_t +argument. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to a +.BR "long double" +argument. +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The conversion specifiers and their meanings are: +.IP "\fRd\fR,\ \fRi\fR" 8 +The +.BR int +argument shall be converted to a signed decimal in the style +\fR"[\-]\fIdddd\fR"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision is 1. The result of converting zero with an explicit +precision of zero shall be no characters. +.IP "\fRo\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned octal format in the style +\fR"\fIdddd\fR"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision is 1. The result of converting zero with an explicit +precision of zero shall be no characters. +.IP "\fRu\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned decimal format in the style +\fR"\fIdddd\fR"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision is 1. The result of converting zero with an explicit +precision of zero shall be no characters. +.IP "\fRx\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned hexadecimal format in the +style \fR"\fIdddd\fR"\fR; the letters +.BR \(dqabcdef\(dq +are used. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer +digits, it shall be expanded with leading zeros. The default precision +is 1. The result of converting zero with an explicit precision of zero +shall be no characters. +.IP "\fRX\fP" 8 +Equivalent to the +.BR x +conversion specifier, except that letters +.BR \(dqABCDEF\(dq +are used instead of +.BR \(dqabcdef\(dq . +.IP "\fRf\fR,\ \fRF\fR" 8 +The +.BR double +argument shall be converted to decimal notation in the style +\fR"[\-]\fIddd\fR.\fIddd\fR"\fR, where the number of digits after the +radix character is equal to the precision specification. If the +precision is missing, it shall be taken as 6; if the precision is +explicitly zero and no +.BR '#' +flag is present, no radix character shall appear. If a radix character +appears, at least one digit appears before it. The low-order digit +shall be rounded in an implementation-defined manner. +.RS 8 +.P +A +.BR double +argument representing an infinity shall be converted in one of the +styles +.BR \(dq[-]inf\(dq +or +.BR \(dq[-]infinity\(dq ; +which style is implementation-defined. A +.BR double +argument representing a NaN shall be converted in one of the styles +\fR"[\-]nan(\fIn-char-sequence\fR)"\fR or +.BR \(dq[-]nan\(dq ; +which style, and the meaning of any +.IR n-char-sequence , +is implementation-defined. The +.BR F +conversion specifier produces +.BR \(dqINF\(dq , +.BR \(dqINFINITY\(dq , +or +.BR \(dqNAN\(dq +instead of +.BR \(dqinf\(dq , +.BR \(dqinfinity\(dq , +or +.BR \(dqnan\(dq , +respectively. +.RE +.IP "\fRe\fR,\ \fRE\fR" 8 +The +.BR double +argument shall be converted in the style +\fR"[\-]\fId\fR.\fIddd\fRe\(+-\fIdd\fR"\fR, where there is one digit +before the radix character (which is non-zero if the argument is +non-zero) and the number of digits after it is equal to the precision; +if the precision is missing, it shall be taken as 6; if the precision +is zero and no +.BR '#' +flag is present, no radix character shall appear. The low-order digit +shall be rounded in an implementation-defined manner. The +.BR E +conversion specifier shall produce a number with +.BR 'E' +instead of +.BR 'e' +introducing the exponent. The exponent shall always contain at least +two digits. If the value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in +the style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRg\fR,\ \fRG\fR" 8 +The +.BR double +argument representing a floating-point number shall be converted in the +style +.BR f +or +.BR e +(or in the style +.BR F +or +.BR E +in the case of a +.BR G +conversion specifier), depending on the value converted and the precision. +Let +.BR P +equal the precision if non-zero, 6 if the precision is omitted, or 1 if the +precision is zero. Then, if a conversion with style +.BR E +would have an exponent of +.IR X : +.RS 8 +.IP -- 4 +If +.BR P >\c +.IR X \(>=\-4, +the conversion shall be with style +.BR f +(or +.BR F ) +and precision +.BR P \-(\c +.IR X +1). +.IP -- 4 +Otherwise, the conversion shall be with style +.BR e +(or +.BR E ) +and precision +.BR P \-1. +.P +Finally, unless the +.BR '#' +flag is used, any trailing zeros shall be removed from the fractional +portion of the result and the decimal-point character shall be removed +if there is no fractional portion remaining. +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRa\fR,\ \fRA\fR" 8 +A +.BR double +argument representing a floating-point number shall be converted in the +style \fR"[\-]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there is +one hexadecimal digit (which shall be non-zero if the argument is a +normalized floating-point number and is otherwise unspecified) before +the decimal-point character and the number of hexadecimal digits after +it is equal to the precision; if the precision is missing and FLT_RADIX +is a power of 2, then the precision shall be sufficient for an exact +representation of the value; if the precision is missing and FLT_RADIX +is not a power of 2, then the precision shall be sufficient to +distinguish values of type +.BR double , +except that trailing zeros may be omitted; if the precision is zero and +the +.BR '#' +flag is not specified, no decimal-point character shall appear. The +letters +.BR \(dqabcdef\(dq +shall be used for +.BR a +conversion and the letters +.BR \(dqABCDEF\(dq +for +.BR A +conversion. The +.BR A +conversion specifier produces a number with +.BR 'X' +and +.BR 'P' +instead of +.BR 'x' +and +.BR 'p' . +The exponent shall always contain at least one digit, and only as many +more digits as necessary to represent the decimal exponent of 2. If the +value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRc\fP" 8 +The +.BR int +argument shall be converted to an +.BR "unsigned char" , +and the resulting byte shall be written. +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the +.BR wint_t +argument shall be converted as if by an +.BR ls +conversion specification with no precision and an argument that points +to a two-element array of type +.BR wchar_t , +the first element of which contains the +.BR wint_t +argument to the +.BR ls +conversion specification and the second element contains a null wide +character. +.RE +.IP "\fRs\fP" 8 +The argument shall be a pointer to an array of +.BR char . +Bytes from the array shall be written up to (but not including) any +terminating null byte. If the precision is specified, no more than that +many bytes shall be written. If the precision is not specified or is +greater than the size of the array, the application shall ensure that +the array contains a null byte. +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the argument shall be a pointer to an array +of type +.BR wchar_t . +Wide characters from the array shall be converted to characters (each +as if by a call to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted) up to and including a terminating null wide character. The +resulting characters shall be written up to (but not including) the +terminating null character (byte). If no precision is specified, the +application shall ensure that the array contains a null wide character. +If a precision is specified, no more than that many characters (bytes) +shall be written (including shift sequences, if any), and the array +shall contain a null wide character if, to equal the character sequence +length given by the precision, the function would need to access a wide +character one past the end of the array. In no case shall a partial +character be written. +.RE +.IP "\fRp\fP" 8 +The argument shall be a pointer to +.BR void . +The value of the pointer is converted to a sequence of printable +characters, in an implementation-defined manner. +.IP "\fRn\fP" 8 +The argument shall be a pointer to an integer into which is written the +number of bytes written to the output so far by this call to one of the +\fIfprintf\fR() +functions. No argument is converted. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Print a +.BR '%' +character; no argument is converted. The complete conversion +specification shall be +.BR %% . +.P +If a conversion specification does not match one of the above forms, +the behavior is undefined. If any argument is not the correct type for +the corresponding conversion specification, the behavior is undefined. +.P +In no case shall a nonexistent or small field width cause truncation of +a field; if the result of a conversion is wider than the field width, +the field shall be expanded to contain the conversion result. +Characters generated by +\fIfprintf\fR() +and +\fIprintf\fR() +are printed as if +\fIfputc\fR() +had been called. +.P +For the +.BR a +and +.BR A +conversion specifiers, if FLT_RADIX is a power of 2, the value shall be +correctly rounded to a hexadecimal floating number with the given +precision. +.P +For +.BR a +and +.BR A +conversions, if FLT_RADIX is not a power of 2 and the result is not +exactly representable in the given precision, the result should be one +of the two adjacent numbers in hexadecimal floating style with the +given precision, with the extra stipulation that the error should have +a correct sign for the current rounding direction. +.P +For the +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, if the number of significant decimal digits is +at most DECIMAL_DIG, then the result should be correctly rounded. If +the number of significant decimal digits is more than DECIMAL_DIG but +the source value is exactly representable with DECIMAL_DIG digits, then +the result should be an exact representation with trailing zeros. +Otherwise, the source value is bounded by two adjacent decimal strings +.IR L +< +.IR U , +both having DECIMAL_DIG significant digits; the value of the resultant +decimal string +.IR D +should satisfy +.IR L +<= +.IR D +<= +.IR U , +with the extra stipulation that the error should have a correct sign +for the current rounding direction. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update: +.IP " 1." 4 +Between the call to a successful execution of +\fIfprintf\fR() +or +\fIprintf\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR() +.IP " 2." 4 +Upon successful completion of a call to +\fIdprintf\fR() +.SH "RETURN VALUE" +Upon successful completion, the +\fIdprintf\fR(), +\fIfprintf\fR(), +and +\fIprintf\fR() +functions shall return the number of bytes transmitted. +.P +Upon successful completion, the +\fIsprintf\fR() +function shall return the number of bytes written to +.IR s , +excluding the terminating null byte. +.P +Upon successful completion, the +\fIsnprintf\fR() +function shall return the number of bytes that would be written to +.IR s +had +.IR n +been sufficiently large excluding the terminating null byte. +.P +If an output error was encountered, these functions shall return a +negative value +and set +.IR errno +to indicate the error. +.P +If the value of +.IR n +is zero on a call to +\fIsnprintf\fR(), +nothing shall be written, the number of bytes that would have been +written had +.IR n +been sufficiently large excluding the terminating null shall be +returned, and +.IR s +may be a null pointer. +.SH ERRORS +For the conditions under which +\fIdprintf\fR(), +\fIfprintf\fR(), +and +\fIprintf\fR() +fail and may fail, refer to +.IR "\fIfputc\fR\^(\|)" +or +.IR "\fIfputwc\fR\^(\|)". +.P +In addition, all forms of +\fIfprintf\fR() +shall fail if: +.TP +.BR EILSEQ +A wide-character code that does not correspond to a valid character +has been detected. +.TP +.BR EOVERFLOW +The value to be returned is greater than +{INT_MAX}. +.P +The +\fIdprintf\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.P +The +\fIdprintf\fR(), +\fIfprintf\fR(), +and +\fIprintf\fR() +functions may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +The +\fIsnprintf\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The value of +.IR n +is greater than +{INT_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.SS "Printing Language-Independent Date and Time" +.P +The following statement can be used to print date and time using a +language-independent format: +.sp +.RS 4 +.nf + +printf(format, weekday, month, day, hour, min); +.fi +.P +.RE +.P +For American usage, +.IR format +could be a pointer to the following string: +.sp +.RS 4 +.nf + +"%s, %s %d, %d:%.2d\en" +.fi +.P +.RE +.P +This example would produce the following message: +.sp +.RS 4 +.nf + +Sunday, July 3, 10:02 +.fi +.P +.RE +.P +For German usage, +.IR format +could be a pointer to the following string: +.sp +.RS 4 +.nf + +"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi +.P +.RE +.P +This definition of +.IR format +would produce the following message: +.sp +.RS 4 +.nf + +Sonntag, 3. Juli, 10:02 +.fi +.P +.RE +.SS "Printing File Information" +.P +The following example prints information about the type, permissions, +and number of links of a specific file in a directory. +.P +The first two calls to +\fIprintf\fR() +use data decoded from a previous +\fIstat\fR() +call. The user-defined +\fIstrperm\fR() +function shall return a string similar to the one at the beginning of the +output for the following command: +.sp +.RS 4 +.nf + +ls -l +.fi +.P +.RE +.P +The next call to +\fIprintf\fR() +outputs the owner's name if it is found using +\fIgetpwuid\fR(); +the +\fIgetpwuid\fR() +function shall return a +.BR passwd +structure from which the name of the user is extracted. If the user +name is not found, the program instead prints out the numeric value of +the user ID. +.P +The next call prints out the group name if it is found using +\fIgetgrgid\fR(); +\fIgetgrgid\fR() +is very similar to +\fIgetpwuid\fR() +except that it shall return group information based on the group number. +Once again, if the group is not found, the program prints the numeric +value of the group for the entry. +.P +The final call to +\fIprintf\fR() +prints the size of the file. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +.P +char *strperm (mode_t); +\&... +struct stat statbuf; +struct passwd *pwd; +struct group *grp; +\&... +printf("%10.10s", strperm (statbuf.st_mode)); +printf("%4d", statbuf.st_nlink); +.P +if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); +else + printf(" %-8ld", (long) statbuf.st_uid); +.P +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); +else + printf(" %-8ld", (long) statbuf.st_gid); +.P +printf("%9jd", (intmax_t) statbuf.st_size); +\&... +.fi +.P +.RE +.SS "Printing a Localized Date String" +.P +The following example gets a localized date string. The +\fInl_langinfo\fR() +function shall return the localized date string, which specifies the +order and layout of the date. The +\fIstrftime\fR() +function takes this information and, using the +.BR tm +structure for values, places the date and time information into +.IR datestring . +The +\fIprintf\fR() +function then outputs +.IR datestring +and the name of the entry. +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +struct dirent *dp; +struct tm *tm; +char datestring[256]; +\&... +strftime(datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +.P +printf(" %s %s\en", datestring, dp->d_name); +\&... +.fi +.P +.RE +.SS "Printing Error Information" +.P +The following example uses +\fIfprintf\fR() +to write error information to standard error. +.P +In the first group of calls, the program tries to open the password +lock file named +.BR LOCKFILE . +If the file already exists, this is an error, as indicated by the +O_EXCL flag on the +\fIopen\fR() +function. If the call fails, the program assumes that someone else is +updating the password file, and the program exits. +.P +The next group of calls saves a new password file as the current +password file by creating a link between +.BR LOCKFILE +and the new password file +.BR PASSWDFILE . +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +\&... +int pfd; +\&... +if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en"); + exit(1); +} +\&... +if (link(LOCKFILE,PASSWDFILE) == -1) { + fprintf(stderr, "Link error: %s\en", strerror(errno)); + exit(1); +} +\&... +.fi +.P +.RE +.SS "Printing Usage Information" +.P +The following example checks to make sure the program has the necessary +arguments, and uses +\fIfprintf\fR() +to print usage information if the expected number of arguments is not +present. +.sp +.RS 4 +.nf + +#include +#include +\&... +char *Options = "hdbtl"; +\&... +if (argc < 2) { + fprintf(stderr, "Usage: %s -%s +(\c +.BR '*' ) +in the format string; this ensures the correct number of decimal places +for the element based on the number of elements requested. +.sp +.RS 4 +.nf + +#include +\&... +long i; +char *keystr; +int elementlen, len; +\&... +while (len < elementlen) { +\&... + printf("%s Element%0*ld\en", keystr, elementlen, i); +\&... +} +.fi +.P +.RE +.SS "Creating a Pathname" +.P +The following example creates a pathname using information from a previous +\fIgetpwnam\fR() +function that returned the password database entry of the user. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +\&... +char *pathname; +struct passwd *pw; +size_t len; +\&... +// digits required for pid_t is number of bits times +// log2(10) = approx 10/33 +len = strlen(pw->pw_dir) + 1 + 1+(sizeof(pid_t)*80+32)/33 + + sizeof ".out"; +pathname = malloc(len); +if (pathname != NULL) +{ + snprintf(pathname, len, "%s/%jd.out", pw->pw_dir, + (intmax_t)getpid()); + ... +} +.fi +.P +.RE +.SS "Reporting an Event" +.P +The following example loops until an event has timed out. The +\fIpause\fR() +function waits forever unless it receives a signal. The +\fIfprintf\fR() +statement should never occur due to the possible return values of +\fIpause\fR(). +.sp +.RS 4 +.nf + +#include +#include +#include +#include +\&... +while (!event_complete) { +\&... + if (pause() != -1 || errno != EINTR) + fprintf(stderr, "pause: unknown error: %s\en", strerror(errno)); +} +\&... +.fi +.P +.RE +.SS "Printing Monetary Information" +.P +The following example uses +\fIstrfmon\fR() +to convert a number and store it as a formatted monetary string named +.IR convbuf . +If the first number is printed, the program prints the format and the +description; otherwise, it just prints the number. +.sp +.RS 4 +.nf + +#include +#include +\&... +struct tblfmt { + char *format; + char *description; +}; +.P +struct tblfmt table[] = { + { "%n", "default formatting" }, + { "%11n", "right align within an 11 character field" }, + { "%#5n", "aligned columns for values up to 99\|999" }, + { "%=*#5n", "specify a fill character" }, + { "%=0#5n", "fill characters do not use grouping" }, + { "%\(ha#5n", "disable the grouping separator" }, + { "%\(ha#5.0n", "round off to whole units" }, + { "%\(ha#5.4n", "increase the precision" }, + { "%(#5n", "use an alternative pos/neg style" }, + { "%!(#5n", "disable the currency symbol" }, +}; +\&... +float input[3]; +int i, j; +char convbuf[100]; +\&... +strfmon(convbuf, sizeof(convbuf), table[i].format, input[j]); +.P +if (j == 0) { + printf("%s\t%s\t%s\en", table[i].format, + convbuf, table[i].description); +} +else { + printf("\t%s\en", convbuf); +} +\&... +.fi +.P +.RE +.SS "Printing Wide Characters" +.P +The following example prints a series of wide characters. Suppose that +.BR \(dqL`@`\(dq +expands to three bytes: +.sp +.RS 4 +.nf + +wchar_t wz [3] = L"@@"; // Zero-terminated +wchar_t wn [3] = L"@@@"; // Unterminated +.P +fprintf (stdout,"%ls", wz); // Outputs 6 bytes +fprintf (stdout,"%ls", wn); // Undefined because wn has no terminator +fprintf (stdout,"%4ls", wz); // Outputs 3 bytes +fprintf (stdout,"%4ls", wn); // Outputs 3 bytes; no terminator needed +fprintf (stdout,"%9ls", wz); // Outputs 6 bytes +fprintf (stdout,"%9ls", wn); // Outputs 9 bytes; no terminator needed +fprintf (stdout,"%10ls", wz); // Outputs 6 bytes +fprintf (stdout,"%10ls", wn); // Undefined because wn has no terminator +.fi +.P +.RE +.P +In the last line of the example, after processing three characters, +nine bytes have been output. The fourth character must then be examined +to determine whether it converts to one byte or more. If it converts +to more than one byte, the output is only nine bytes. Since there is +no fourth character in the array, the behavior is undefined. +.SH "APPLICATION USAGE" +If the application calling +\fIfprintf\fR() +has any objects of type +.BR wint_t +or +.BR wchar_t , +it must also include the +.IR +header to have these objects defined. +.SH RATIONALE +If an implementation detects that there are insufficient +arguments for the format, it is recommended that the function +should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputc\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrfmon\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fputc.3p b/upstream/archlinux/man3p/fputc.3p new file mode 100644 index 00000000..40fc1504 --- /dev/null +++ b/upstream/archlinux/man3p/fputc.3p @@ -0,0 +1,159 @@ +'\" et +.TH FPUTC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fputc +\(em put a byte on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fputc(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfputc\fR() +function shall write the byte specified by +.IR c +(converted to an +.BR "unsigned char" ) +to the output stream pointed to by +.IR stream , +at the position indicated by the associated file-position indicator for +the stream (if defined), and shall advance the indicator appropriately. +If the file cannot support positioning requests, or if the stream was +opened with append mode, the byte shall be appended to the output +stream. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputc\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfputc\fR() +shall return the value it has written. Otherwise, it shall return EOF, +the error indicator for the stream shall be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfputc\fR() +function shall fail if either the +.IR stream +is unbuffered or the +.IR stream 's +buffer needs to be flushed, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for writing. +.TP +.BR EFBIG +An attempt was made to write to a file that exceeds the maximum file +size. +.TP +.BR EFBIG +An attempt was made to write to a file that exceeds the file +size limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to write to its controlling terminal, +TOSTOP is set, the calling thread is not blocking SIGTTOU, the process +is not ignoring SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the +thread. +.br +.P +The +\fIfputc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was +outside the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fputs.3p b/upstream/archlinux/man3p/fputs.3p new file mode 100644 index 00000000..9fe6576e --- /dev/null +++ b/upstream/archlinux/man3p/fputs.3p @@ -0,0 +1,156 @@ +'\" et +.TH FPUTS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fputs +\(em put a string on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fputs(const char *restrict \fIs\fP, FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfputs\fR() +function shall write the null-terminated string pointed to by +.IR s +to the stream pointed to by +.IR stream . +The terminating null byte shall not be written. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputs\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfputs\fR() +shall return a non-negative number. Otherwise, it shall return EOF, +set an error indicator for the stream, +and set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Printing to Standard Output" +.P +The following example gets the current time, converts it to a string +using +\fIlocaltime\fR() +and +\fIasctime\fR(), +and prints it to standard output using +\fIfputs\fR(). +It then prints the number of minutes to an event for which it is +waiting. +.sp +.RS 4 +.nf + +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +fputs(asctime(localtime(&now)), stdout); +printf("There are still %d minutes to the event.\en", + minutes_to_event); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputs\fR() +function appends a + +while +\fIfputs\fR() +does not. +.P +This volume of POSIX.1\(hy2017 requires that successful completion simply return a non-negative +integer. There are at least three known different implementation +conventions for this requirement: +.IP " *" 4 +Return a constant value. +.IP " *" 4 +Return the last character written. +.IP " *" 4 +Return the number of bytes written. Note that this implementation +convention cannot be adhered to for strings longer than +{INT_MAX} +bytes as the value would not be representable in the return type of the +function. For backwards-compatibility, implementations can return the +number of bytes for strings of up to +{INT_MAX} +bytes, and return +{INT_MAX} +for all longer strings. +.SH RATIONALE +The +\fIfputs\fR() +function is one whose source code was specified in the referenced \fIThe C Programming Language\fP. In the +original edition, the function had no defined return value, yet many +practical implementations would, as a side-effect, return the value of the +last character written as that was the value remaining in the accumulator +used as a return value. In the second edition of the book, either the +fixed value 0 or EOF would be returned depending upon the return value of +\fIferror\fR(); +however, for compatibility with extant implementations, several +implementations would, upon success, return a positive value representing +the last byte written. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fputwc.3p b/upstream/archlinux/man3p/fputwc.3p new file mode 100644 index 00000000..02d877b7 --- /dev/null +++ b/upstream/archlinux/man3p/fputwc.3p @@ -0,0 +1,164 @@ +'\" et +.TH FPUTWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fputwc +\(em put a wide-character code on a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t fputwc(wchar_t \fIwc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfputwc\fR() +function shall write the character corresponding to the wide-character +code +.IR wc +to the output stream pointed to by +.IR stream , +at the position indicated by the associated file-position indicator for +the stream (if defined), and advances the indicator appropriately. If +the file cannot support positioning requests, or if the stream was +opened with append mode, the character is appended to the output +stream. If an error occurs while writing the character, the shift +state of the output file is left in an undefined state. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputwc\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.P +The +\fIfputwc\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, +\fIfputwc\fR() +shall return +.IR wc . +Otherwise, it shall return WEOF, the error indicator for the stream shall +be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfputwc\fR() +function shall fail if either the stream is unbuffered or data in the +.IR stream 's +buffer needs to be written, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor underlying +.IR stream +and the thread would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not a valid file descriptor open for writing. +.TP +.BR EFBIG +An attempt was made to write to a file that exceeds the maximum file +size or the file size limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EILSEQ +The wide-character code +.IR wc +does not correspond to a valid character. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to write to its controlling terminal, +TOSTOP is set, the calling thread is not blocking SIGTTOU, the process +is not ignoring SIGTTOU, and the process group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process. A SIGPIPE signal shall also be sent to the +thread. +.P +The +\fIfputwc\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was +outside the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fputws.3p b/upstream/archlinux/man3p/fputws.3p new file mode 100644 index 00000000..bab4c9ca --- /dev/null +++ b/upstream/archlinux/man3p/fputws.3p @@ -0,0 +1,115 @@ +'\" et +.TH FPUTWS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fputws +\(em put a wide-character string on a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fputws(const wchar_t *restrict \fIws\fP, FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfputws\fR() +function shall write a character string corresponding to the +(null-terminated) wide-character string pointed to by +.IR ws +to the stream pointed to by +.IR stream . +No character corresponding to the terminating null wide-character code +shall be written. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfputws\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfputws\fR() +shall return a non-negative number. Otherwise, +it shall return \-1, set an error indicator for the stream, +and set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfputws\fR() +function does not append a +. +.P +This volume of POSIX.1\(hy2017 requires that successful completion simply return a non-negative +integer. There are at least three known different implementation +conventions for this requirement: +.IP " *" 4 +Return a constant value. +.IP " *" 4 +Return the last character written. +.IP " *" 4 +Return the number of bytes written. Note that this implementation +convention cannot be adhered to for strings longer than +{INT_MAX} +bytes as the value would not be representable in the return type of the +function. For backwards-compatibility, implementations can return the +number of bytes for strings of up to +{INT_MAX} +bytes, and return +{INT_MAX} +for all longer strings. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fread.3p b/upstream/archlinux/man3p/fread.3p new file mode 100644 index 00000000..0784dc01 --- /dev/null +++ b/upstream/archlinux/man3p/fread.3p @@ -0,0 +1,193 @@ +'\" et +.TH FREAD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fread +\(em binary input +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t fread(void *restrict \fIptr\fP, size_t \fIsize\fP, size_t \fInitems\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfread\fR() +function shall read into the array pointed to by +.IR ptr +up to +.IR nitems +elements whose size is specified by +.IR size +in bytes, from the stream pointed to by +.IR stream . +For each object, +.IR size +calls shall be made to the +\fIfgetc\fR() +function and the results stored, in the order read, in an array of +.BR "unsigned char" +exactly overlaying the object. The file position indicator for the +stream (if defined) shall be advanced by the number of bytes +successfully read. If an error occurs, the resulting value of the file +position indicator for the stream is unspecified. If a partial element +is read, its value is unspecified. +.P +The +\fIfread\fR() +function may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be +marked for update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIfread\fR() +shall return the number of elements successfully read which is less than +.IR nitems +only if a read error or end-of-file is encountered. If +.IR size +or +.IR nitems +is 0, +\fIfread\fR() +shall return 0 and the contents of the array and the state of the +stream remain unchanged. Otherwise, if a read error occurs, the error +indicator for the stream shall be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading from a Stream" +.P +The following example transfers a single 100-byte fixed length +record from the +.IR fp +stream into the array pointed to by +.IR buf . +.sp +.RS 4 +.nf + +#include +\&... +size_t elements_read; +char buf[100]; +FILE *fp; +\&... +elements_read = fread(buf, sizeof(buf), 1, fp); +\&... +.fi +.P +.RE +.P +If a read error occurs, +.IR elements_read +will be zero but the number of bytes read from the stream could be +anything from zero to +.IR sizeof ( buf )\-1. +.P +The following example reads multiple single-byte elements from the +.IR fp +stream into the array pointed to by +.IR buf . +.sp +.RS 4 +.nf + +#include +\&... +size_t bytes_read; +char buf[100]; +FILE *fp; +\&... +bytes_read = fread(buf, 1, sizeof(buf), fp); +\&... +.fi +.P +.RE +.P +If a read error occurs, +.IR bytes_read +will contain the number of bytes read from the stream. +.SH "APPLICATION USAGE" +The +\fIferror\fR() +or +\fIfeof\fR() +functions must be used to distinguish between an error condition and an +end-of-file condition. +.P +Because of possible differences in element length and byte ordering, +files written using +\fIfwrite\fR() +are application-dependent, and possibly cannot be read using +\fIfread\fR() +by a different application or by the same application on a different +processor. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgets\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/free.3p b/upstream/archlinux/man3p/free.3p new file mode 100644 index 00000000..b84ece0d --- /dev/null +++ b/upstream/archlinux/man3p/free.3p @@ -0,0 +1,86 @@ +'\" et +.TH FREE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +free +\(em free allocated memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void free(void *\fIptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfree\fR() +function shall cause the space pointed to by +.IR ptr +to be deallocated; that is, made available for further allocation. If +.IR ptr +is a null pointer, no action shall occur. Otherwise, if the argument +does not match a pointer earlier returned by a function in POSIX.1\(hy2008 that +allocates memory as if by +\fImalloc\fR(), +or if the space has been deallocated by a call to +\fIfree\fR() +or +\fIrealloc\fR(), +the behavior is undefined. +.P +Any use of a pointer that refers to freed space results in undefined +behavior. +.SH "RETURN VALUE" +The +\fIfree\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +There is now no requirement for the implementation to support the +inclusion of +.IR . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcalloc\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIposix_memalign\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/freeaddrinfo.3p b/upstream/archlinux/man3p/freeaddrinfo.3p new file mode 100644 index 00000000..e64225e8 --- /dev/null +++ b/upstream/archlinux/man3p/freeaddrinfo.3p @@ -0,0 +1,556 @@ +'\" et +.TH FREEADDRINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +freeaddrinfo, +getaddrinfo +\(em get address information +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +void freeaddrinfo(struct addrinfo *\fIai\fP); +int getaddrinfo(const char *restrict \fInodename\fP, + const char *restrict \fIservname\fP, + const struct addrinfo *restrict \fIhints\fP, + struct addrinfo **restrict \fIres\fP); +.fi +.SH DESCRIPTION +The +\fIfreeaddrinfo\fR() +function shall free one or more +.BR addrinfo +structures returned by +\fIgetaddrinfo\fR(), +along with any additional storage associated with those structures. If +the +.IR ai_next +field of the structure is not null, the entire list of structures shall +be freed. The +\fIfreeaddrinfo\fR() +function shall support the freeing of arbitrary sublists of an +.BR addrinfo +list originally returned by +\fIgetaddrinfo\fR(). +.P +The +\fIgetaddrinfo\fR() +function shall translate the name of a service location (for example, a +host name) and/or a service name +and shall return a set of socket addresses and associated information +to be used in creating a socket with which to address the specified +service. +.TP 10 +.BR Note: +In many cases it is implemented by the Domain Name System, +as documented in RFC\ 1034, RFC\ 1035, and RFC\ 1886. +.P +.P +The +\fIfreeaddrinfo\fR() +and +\fIgetaddrinfo\fR() +functions shall be thread-safe. +.P +The +.IR nodename +and +.IR servname +arguments are either null pointers or pointers to null-terminated +strings. One or both of these two arguments shall be supplied by the +application as a non-null pointer. +.P +The format of a valid name depends on the address family or families. +If a specific family is not given and the name could be interpreted as +valid within multiple supported families, the implementation shall +attempt to resolve the name in all supported families and, in absence +of errors, one or more results shall be returned. +.P +If the +.IR nodename +argument is not null, it can be a descriptive name or can be an address +string. +If the specified address family is AF_INET, +AF_INET6, +or AF_UNSPEC, valid descriptive names include host names. If the +specified address family is AF_INET or AF_UNSPEC, address strings using +Internet standard dot notation as specified in +.IR "\fIinet_addr\fR\^(\|)" +are valid. +.P +If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 +text forms described in +.IR "\fIinet_ntop\fR\^(\|)" +are valid. +.P +If +.IR nodename +is not null, the requested service location is named by +.IR nodename ; +otherwise, the requested service location is local to the caller. +.P +If +.IR servname +is null, the call shall return network-level addresses for the +specified +.IR nodename. +If +.IR servname +is not null, it is a null-terminated character string identifying the +requested service. This can be either a descriptive name or a numeric +representation suitable for use with the address family or families. +If the specified address family is AF_INET, +AF_INET6, +or AF_UNSPEC, the service can be specified as a string specifying a +decimal port number. +.P +If the +.IR hints +argument is not null, it refers to a structure containing input values +that directs the operation by providing options and by limiting the +returned information to a specific socket type, address family, and/or +protocol, as described below. The application shall ensure that each of the +.IR ai_addrlen , +.IR ai_addr , +.IR ai_canonname , +and +.IR ai_next +members, as well as each of the non-standard additional members, +if any, of this +.IR hints +structure is initialized. If any of these members has a value +other than the value that would result from default initialization, +the behavior is implementation-defined. A value of AF_UNSPEC for +.IR ai_family +means that the caller shall accept any address family. A value of zero +for +.IR ai_socktype +means that the caller shall accept any socket type. A value of zero for +.IR ai_protocol +means that the caller shall accept any protocol. If +.IR hints +is a null pointer, the behavior shall be as if it referred to a +structure containing the value zero for the +.IR ai_flags , +.IR ai_socktype , +and +.IR ai_protocol +fields, and AF_UNSPEC for the +.IR ai_family +field. +.P +The +.IR ai_flags +field to which the +.IR hints +parameter points shall be set to zero or be the bitwise-inclusive +OR of one or more of the values AI_PASSIVE, AI_CANONNAME, +AI_NUMERICHOST, AI_NUMERICSERV, AI_V4MAPPED, AI_ALL, and AI_ADDRCONFIG. +.P +If the AI_PASSIVE flag is specified, the returned address information +shall be suitable for use in binding a socket for accepting incoming +connections for the specified service. In this case, if the +.IR nodename +argument is null, then the IP address portion of the socket address +structure shall be set to INADDR_ANY for an IPv4 address or +IN6ADDR_ANY_INIT for an IPv6 address. If the AI_PASSIVE flag is not +specified, the returned address information shall be suitable for a call +to +\fIconnect\fR() +(for a connection-mode protocol) or for a call to +\fIconnect\fR(), +\fIsendto\fR(), +or +\fIsendmsg\fR() +(for a connectionless protocol). In this case, if the +.IR nodename +argument is null, then the IP address portion of the socket address +structure shall be set to the loopback address. The AI_PASSIVE flag shall +be ignored if the +.IR nodename +argument is not null. +.P +If the AI_CANONNAME flag is specified and the +.IR nodename +argument is not null, the function shall attempt to determine the +canonical name corresponding to +.IR nodename +(for example, if +.IR nodename +is an alias or shorthand notation for a complete name). +.TP 10 +.BR Note: +Since different implementations use different conceptual models, the +terms ``canonical name'' and ``alias'' cannot be precisely defined for +the general case. However, Domain Name System implementations are +expected to interpret them as they are used in RFC\ 1034. +.RS 10 +.P +A numeric host address string is not a ``name'', and thus does not have +a ``canonical name'' form; no address to host name translation is +performed. See below for handling of the case where a canonical name +cannot be obtained. +.RE +.P +.P +If the AI_NUMERICHOST flag is specified, then a non-null +.IR nodename +string supplied shall be a numeric host address string. Otherwise, an +.BR [EAI_NONAME] +error is returned. This flag shall prevent any type of name resolution +service (for example, the DNS) from being invoked. +.P +If the AI_NUMERICSERV flag is specified, then a non-null +.IR servname +string supplied shall be a numeric port string. Otherwise, an +.BR [EAI_NONAME] +error shall be returned. This flag shall prevent any type of name +resolution service (for example, NIS+) from being invoked. +.P +By default, with an +.IR ai_family +of AF_INET6, +\fIgetaddrinfo\fR() +shall return only IPv6 addresses. If the AI_V4MAPPED flag is +specified along with an +.IR ai_family +of AF_INET6, then +\fIgetaddrinfo\fR() +shall return IPv4-mapped IPv6 addresses on finding no matching IPv6 +addresses. The AI_V4MAPPED flag shall be ignored unless +.IR ai_family +equals AF_INET6. If the AI_ALL flag is used with the AI_V4MAPPED flag, +then +\fIgetaddrinfo\fR() +shall return all matching IPv6 and IPv4 addresses. The AI_ALL flag +without the AI_V4MAPPED flag shall be ignored. +.P +If the AI_ADDRCONFIG flag is specified, IPv4 addresses shall be +returned only if an IPv4 address is configured on the local system, +and IPv6 addresses shall be returned only if an IPv6 address is +configured on the local system. +.P +The +.IR ai_socktype +field to which argument +.IR hints +points specifies the socket type for the service, as defined in +.IR "\fIsocket\fR\^(\|)". +If a specific socket type is not given (for example, a value of zero) +and the service name could be interpreted as valid with multiple +supported socket types, the implementation shall attempt to resolve the +service name for all supported socket types and, in the absence of +errors, all possible results shall be returned. A non-zero socket type +value shall limit the returned information to values with the specified +socket type. +.P +If the +.IR ai_family +field to which +.IR hints +points has the value AF_UNSPEC, addresses shall be returned for use +with any address family that can be used with the specified +.IR nodename +and/or +.IR servname . +Otherwise, addresses shall be returned for use only with the specified +address family. If +.IR ai_family +is not AF_UNSPEC and +.IR ai_protocol +is not zero, then addresses shall be returned for use only with the +specified address family and protocol; the value of +.IR ai_protocol +shall be interpreted as in a call to the +\fIsocket\fR() +function with the corresponding values of +.IR ai_family +and +.IR ai_protocol . +.SH "RETURN VALUE" +A zero return value for +\fIgetaddrinfo\fR() +indicates successful completion; a non-zero return value indicates +failure. The possible values for the failures are listed in the +ERRORS section. +.P +Upon successful return of +\fIgetaddrinfo\fR(), +the location to which +.IR res +points shall refer to a linked list of +.BR addrinfo +structures, each of which shall specify a socket address and +information for use in creating a socket with which to use that socket +address. The list shall include at least one +.BR addrinfo +structure. The +.IR ai_next +field of each structure contains a pointer to the next structure on the +list, or a null pointer if it is the last structure on the list. Each +structure on the list shall include values for use with a call to the +\fIsocket\fR() +function, and a socket address for use with the +\fIconnect\fR() +function or, if the AI_PASSIVE flag was specified, for use with the +\fIbind\fR() +function. The fields +.IR ai_family , +.IR ai_socktype , +and +.IR ai_protocol +shall be usable as the arguments to the +\fIsocket\fR() +function to create a socket suitable for use with the returned +address. The fields +.IR ai_addr +and +.IR ai_addrlen +are usable as the arguments to the +\fIconnect\fR() +or +\fIbind\fR() +functions with such a socket, according to the AI_PASSIVE flag. +.P +If +.IR nodename +is not null, and if requested by the AI_CANONNAME flag, the +.IR ai_canonname +field of the first returned +.BR addrinfo +structure shall point to a null-terminated string containing the +canonical name corresponding to the input +.IR nodename ; +if the canonical name is not available, then +.IR ai_canonname +shall refer to the +.IR nodename +argument or a string with the same contents. The contents of the +.IR ai_flags +field of the returned structures are undefined. +.P +All fields in socket address structures returned by +\fIgetaddrinfo\fR() +that are not filled in through an explicit argument (for example, +.IR sin6_flowinfo ) +shall be set to zero. +.TP 10 +.BR Note: +This makes it easier to compare socket address structures. +.P +.SH ERRORS +The +\fIgetaddrinfo\fR() +function shall fail and return the corresponding error value if: +.IP [EAI_AGAIN] 12 +The name could not be resolved at this time. Future attempts may +succeed. +.IP [EAI_BADFLAGS] 12 +.br +The +.IR flags +parameter had an invalid value. +.IP [EAI_FAIL] 12 +A non-recoverable error occurred when attempting to resolve the name. +.IP [EAI_FAMILY] 12 +The address family was not recognized. +.IP [EAI_MEMORY] 12 +There was a memory allocation failure when trying to allocate storage +for the return value. +.IP [EAI_NONAME] 12 +The name does not resolve for the supplied parameters. +.RS 12 +.P +Neither +.IR nodename +nor +.IR servname +were supplied. At least one of these shall be supplied. +.RE +.IP [EAI_SERVICE] 12 +The service passed was not recognized for the specified socket type. +.IP [EAI_SOCKTYPE] 12 +.br +The intended socket type was not recognized. +.IP [EAI_SYSTEM] 12 +A system error occurred; the error code can be found in +.IR errno . +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following (incomplete) program demonstrates the use of +\fIgetaddrinfo\fR() +to obtain the socket address structure(s) for the service named in the +program's command-line argument. The program then loops through each +of the address structures attempting to create and bind a socket to the +address, until it performs a successful +\fIbind\fR(). +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +.P +int +main(int argc, char *argv[]) +{ + struct addrinfo *result, *rp; + int sfd, s; +.P + if (argc != 2) { + fprintf(stderr, "Usage: %s port\en", argv[0]); + exit(EXIT_FAILURE); + } +.P + struct addrinfo hints = {0}; + hints.ai_family = AF_UNSPEC; + hints.ai_socktype = SOCK_DGRAM; + hints.ai_flags = AI_PASSIVE; + hints.ai_protocol = 0; +.P + s = getaddrinfo(NULL, argv[1], &hints, &result); + if (s != 0) { + fprintf(stderr, "getaddrinfo: %s\en", gai_strerror(s)); + exit(EXIT_FAILURE); + } +.P + /* getaddrinfo() returns a list of address structures. + Try each address until a successful bind(). + If socket(2) (or bind(2)) fails, close the socket + and try the next address. */ +.P + for (rp = result; rp != NULL; rp = rp->ai_next) { + sfd = socket(rp->ai_family, rp->ai_socktype, + rp->ai_protocol); + if (sfd == -1) + continue; +.P + if (bind(sfd, rp->ai_addr, rp->ai_addrlen) == 0) + break; /* Success */ +.P + close(sfd); + } +.P + if (rp == NULL) { /* No address succeeded */ + fprintf(stderr, "Could not bind\en"); + exit(EXIT_FAILURE); + } +.P + freeaddrinfo(result); /* No longer needed */ +.P + /* ... use socket bound to sfd ... */ +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +If the caller handles only TCP and not UDP, for example, then the +.IR ai_protocol +member of the +.IR hints +structure should be set to IPPROTO_TCP when +\fIgetaddrinfo\fR() +is called. +.P +If the caller handles only IPv4 and not IPv6, then the +.IR ai_family +member of the +.IR hints +structure should be set to AF_INET when +\fIgetaddrinfo\fR() +is called. +.P +Although it is common practice to initialize the +.IR hints +structure using: +.sp +.RS 4 +.nf + +struct addrinfo hints; +memset(&hints, 0, sizeof hints); +.fi +.P +.RE +.P +this method is not portable according to this standard, because +the structure can contain pointer or floating-point members that +are not required to have an all-bits-zero representation after +default initialization. Portable methods make use of default +initialization; for example: +.sp +.RS 4 +.nf + +struct addrinfo hints = { 0 }; +.fi +.P +.RE +.P +or: +.sp +.RS 4 +.nf + +static struct addrinfo hints_init; +struct addrinfo hints = hints_init; +.fi +.P +.RE +.P +A future version of this standard may require that a pointer object +with an all-bits-zero representation is a null pointer, and that +.BR addrinfo +does not have any floating-point members if a floating-point +object with an all-bits-zero representation does not have the value 0.0. +.P +The term ``canonical name'' is misleading; it is taken from the Domain +Name System (RFC\ 2181). It should be noted that the canonical name is +a result of alias processing, and not necessarily a unique attribute of +a host, address, or set of addresses. See RFC\ 2181 for more discussion +of this in the Domain Name System context. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconnect\fR\^(\|)", +.IR "\fIendservent\fR\^(\|)", +.IR "\fIgai_strerror\fR\^(\|)", +.IR "\fIgetnameinfo\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/freelocale.3p b/upstream/archlinux/man3p/freelocale.3p new file mode 100644 index 00000000..dcd4779f --- /dev/null +++ b/upstream/archlinux/man3p/freelocale.3p @@ -0,0 +1,104 @@ +'\" et +.TH FREELOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +freelocale +\(em free resources allocated for a locale object +.SH SYNOPSIS +.LP +.nf +#include +.P +void freelocale(locale_t \fIlocobj\fP); +.fi +.SH DESCRIPTION +The +\fIfreelocale\fR() +function shall cause the resources allocated for a locale object +returned by a call to the +\fInewlocale\fR() +or +\fIduplocale\fR() +functions to be released. +.P +The behavior is undefined if the +.IR locobj +argument is the special locale object LC_GLOBAL_LOCALE or is not a valid +locale object handle. +.P +Any use of a locale object that has been freed results in undefined +behavior. +.SH "RETURN VALUE" +None. +.SH ERRORS +None. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Freeing Up a Locale Object" +.P +The following example shows a code fragment to free a locale object +created by +\fInewlocale\fR(): +.sp +.RS 4 +.nf + +#include +\&... +.P +/* Every locale object allocated with newlocale() should be + * freed using freelocale(): + */ +.P +locale_t loc; +.P +/* Get the locale. */ +.P +loc = newlocale (LC_CTYPE_MASK | LC_TIME_MASK, "locname", NULL); +.P +/* ... Use the locale object ... */ +\&... +.P +/* Free the locale object resources. */ +freelocale (loc); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIduplocale\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/freopen.3p b/upstream/archlinux/man3p/freopen.3p new file mode 100644 index 00000000..1d233448 --- /dev/null +++ b/upstream/archlinux/man3p/freopen.3p @@ -0,0 +1,365 @@ +'\" et +.TH FREOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +freopen +\(em open a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *freopen(const char *restrict \fIpathname\fP, const char *restrict \fImode\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfreopen\fR() +function shall first attempt to flush the stream associated with +.IR stream +as if by a call to +.IR fflush ( stream ). +Failure to flush the stream successfully shall be ignored. If +.IR pathname +is not a null pointer, +\fIfreopen\fR() +shall close any file descriptor associated with +.IR stream . +Failure to close the file descriptor successfully shall be ignored. +The error and end-of-file indicators for the stream shall be +cleared. +.P +The +\fIfreopen\fR() +function shall open the file whose pathname is the string pointed to by +.IR pathname +and associate the stream pointed to by +.IR stream +with it. The +.IR mode +argument shall be used just as in +\fIfopen\fR(). +.P +The original stream shall be closed regardless of whether the +subsequent open succeeds. +.P +If +.IR pathname +is a null pointer, the +\fIfreopen\fR() +function shall attempt to change the mode of the stream to that +specified by +.IR mode , +as if the name of the file currently associated with the stream had +been used. In this case, the file descriptor associated with the stream +need not be closed if the call to +\fIfreopen\fR() +succeeds. It is implementation-defined which changes of mode are +permitted (if any), and under what circumstances. +.P +After a successful call to the +\fIfreopen\fR() +function, the orientation of the stream shall be cleared, +the encoding rule shall be cleared, +and the associated +.BR mbstate_t +object shall be set to describe an initial conversion state. +.P +If +.IR pathname +is not a null pointer, or if +.IR pathname +is a null pointer and the specified mode change necessitates the file +descriptor associated with the stream to be closed and reopened, the +file descriptor associated with the reopened stream shall be allocated +and opened as if by a call to +\fIopen\fR() +with the following flags: +.TS +center box tab(!); +cB | cB +l | l. +\fIfreopen\fP(\^) Mode!\fIopen\fP(\^) Flags +_ +\fIr\fR or \fIrb\fR!O_RDONLY +\fIw\fR or \fIwb\fR!O_WRONLY|O_CREAT|O_TRUNC +\fIa\fR or \fIab\fR!O_WRONLY|O_CREAT|O_APPEND +\fIr+\fR or \fIrb+\fR or \fIr+b\fR!O_RDWR +\fIw+\fR or \fIwb+\fR or \fIw+b\fR!O_RDWR|O_CREAT|O_TRUNC +\fIa+\fR or \fIab+\fR or \fIa+b\fR!O_RDWR|O_CREAT|O_APPEND +.TE +.SH "RETURN VALUE" +Upon successful completion, +\fIfreopen\fR() +shall return the value of +.IR stream . +Otherwise, a null pointer shall be returned, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIfreopen\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or the +file exists and the permissions specified by +.IR mode +are denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created. +.TP +.BR EBADF +The file descriptor underlying the stream is not a valid file +descriptor when +.IR pathname +is a null pointer. +.TP +.BR EINTR +A signal was caught during +\fIfreopen\fR(). +.TP +.BR EISDIR +The named file is a directory and +.IR mode +requires write access. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOENT +The +.IR mode +string begins with +.BR 'r' +and a component of +.IR pathname +does not name an existing file, or +.IR mode +begins with +.BR 'w' +or +.BR 'a' +and a component of the path prefix of +.IR pathname +does not name an existing file, or +.IR pathname +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR pathname +without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory or file system that would contain the new file cannot be +expanded, the file does not exist, and it was to be created. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR pathname +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.TP +.BR ENXIO +The named file is a character special or block special file, and the +device associated with this special file does not exist. +.TP +.BR EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.TP +.BR EROFS +The named file resides on a read-only file system and +.IR mode +requires write access. +.P +The +\fIfreopen\fR() +function may fail if: +.TP +.BR EBADF +The mode with which the file descriptor underlying the stream was +opened does not support the requested mode when +.IR pathname +is a null pointer. +.TP +.BR EINVAL +The value of the +.IR mode +argument is not valid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP +.BR ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and +.IR mode +requires write access. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Directing Standard Output to a File" +.P +The following example logs all standard output to the +.BR /tmp/logfile +file. +.sp +.RS 4 +.nf + +#include +\&... +FILE *fp; +\&... +fp = freopen ("/tmp/logfile", "a+", stdout); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIfreopen\fR() +function is typically used to attach the pre-opened +.IR streams +associated with +.IR stdin , +.IR stdout , +and +.IR stderr +to other files. +.P +Since implementations are not required to support any stream mode changes +when the +.IR pathname +argument is NULL, portable applications cannot rely on the use of +\fIfreopen\fR() +to change the stream mode, and use of this feature is discouraged. The +feature was originally added to the ISO\ C standard in order to facilitate changing +.IR stdin +and +.IR stdout +to binary mode. Since a +.BR 'b' +character in the mode has no effect on POSIX systems, this use of the +feature is unnecessary in POSIX applications. However, even though the +.BR 'b' +is ignored, a successful call to +.IR freopen \c +(NULL, "\fIwb\fR", \fIstdout\fR) does have an effect. In particular, +for regular files it truncates the file and sets the file-position +indicator for the stream to the start of the file. It is possible that +these side-effects are an unintended consequence of the way the feature +is specified in the ISO/IEC\ 9899:\|1999 standard, but unless or until the ISO\ C standard is changed, +applications which successfully call +.IR freopen \c +(NULL, "\fIwb\fR", \fIstdout\fR) will behave in unexpected ways on +conforming systems in situations such as: +.sp +.RS 4 +.nf + +{ appl file1; appl file2; } > file3 +.fi +.P +.RE +.P +which will result in +.BR file3 +containing only the output from the second invocation of +.IR appl . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfflush\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fImbsinit\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIopen_memstream\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/frexp.3p b/upstream/archlinux/man3p/frexp.3p new file mode 100644 index 00000000..6bcb50de --- /dev/null +++ b/upstream/archlinux/man3p/frexp.3p @@ -0,0 +1,99 @@ +'\" et +.TH FREXP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +frexp, +frexpf, +frexpl +\(em extract mantissa and exponent from a double precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double frexp(double \fInum\fP, int *\fIexp\fP); +float frexpf(float \fInum\fP, int *\fIexp\fP); +long double frexpl(long double \fInum\fP, int *\fIexp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall break a floating-point number +.IR num +into a normalized fraction and an integral power of 2. The integer +exponent shall be stored in the +.BR int +object pointed to by +.IR exp . +.SH "RETURN VALUE" +For finite arguments, these functions shall return the value +.IR x , +such that +.IR x +has a magnitude in the interval [\(12,1) or 0, and +.IR num +equals +.IR x +times 2 raised to the power *\fIexp\fP. +.P +If +.IR num +is NaN, a NaN shall be returned, and the value of *\fIexp\fP is +unspecified. +.P +If +.IR num +is \(+-0, \(+-0 shall be returned, and the value of *\fIexp\fP shall be +0. +.P +If +.IR num +is \(+-Inf, +.IR num +shall be returned, and the value of *\fIexp\fP is unspecified. +.SH ERRORS +No errors are defined. +.P +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisnan\fR\^(\|)", +.IR "\fIldexp\fR\^(\|)", +.IR "\fImodf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fscanf.3p b/upstream/archlinux/man3p/fscanf.3p new file mode 100644 index 00000000..68e9ad0d --- /dev/null +++ b/upstream/archlinux/man3p/fscanf.3p @@ -0,0 +1,883 @@ +'\" et +.TH FSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fscanf, +scanf, +sscanf +\(em convert formatted input +.SH SYNOPSIS +.LP +.nf +#include +.P +int fscanf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, ...); +int scanf(const char *restrict \fIformat\fP, ...); +int sscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfscanf\fR() +function shall read from the named input +.IR stream . +The +\fIscanf\fR() +function shall read from the standard input stream +.IR stdin . +The +\fIsscanf\fR() +function shall read from the string +.IR s . +Each function reads bytes, interprets them according to a format, and +stores the results in its arguments. Each expects, as arguments, a +control string +.IR format +described below, and a set of +.IR pointer +arguments indicating where the converted input should be stored. The +result is undefined if there are insufficient arguments for the +format. If the format is exhausted while arguments remain, the excess +arguments shall be evaluated but otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier character +.BR % +(see below) is replaced by the sequence \fR"%\fIn\fR$"\fR, where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}]. +This feature provides for the definition of format strings that select +arguments in an order appropriate to specific languages. In format +strings containing the \fR"%\fIn\fR$"\fR form of conversion +specifications, +it is unspecified whether numbered arguments in the argument list can +be referenced from the format string more than once. +.P +The +.IR format +can contain either form of a conversion specification\(emthat is, +.BR % +or \fR"%\fIn\fR$"\fR\(embut the two forms cannot be mixed +within a single +.IR format +string. The only exception to this is that +.BR %% +or +.BR %* +can be mixed with the \fR"%\fIn\fR$"\fR form. When numbered argument +specifications are used, specifying the +.IR N th +argument requires that all the leading arguments, from the first to +the (\c +.IR N \-1)th, +are pointers. +.P +The +\fIfscanf\fR() +function in all its forms shall allow detection of a language-dependent +radix character in the input string. The radix character is defined in +the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +The format is a character string, beginning and ending in its initial +shift state, if any, composed of zero or more directives. Each +directive is composed of one of the following: +one or more white-space characters (\c +, +, +, +, +or +); +an ordinary character (neither +.BR '%' +nor a white-space character); or a conversion specification. Each +conversion specification is introduced by the character +.BR '%' +or the character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +An optional assignment-suppressing character +.BR '*' . +.IP " *" 4 +An optional non-zero decimal integer that specifies the maximum field +width. +.IP " *" 4 +An optional assignment-allocation character +.BR 'm' . +.IP " *" 4 +An option length modifier that specifies the size of the receiving +object. +.IP " *" 4 +A +.IR "conversion specifier" +character that specifies the type of conversion to be applied. The +valid conversion specifiers are described below. +.P +The +\fIfscanf\fR() +functions shall execute each directive of the format in turn. If a +directive fails, as detailed below, the function shall return. Failures +are described as input failures (due to the unavailability of input +bytes) or matching failures (due to inappropriate input). +.P +A directive composed of one or more white-space characters shall be +executed by reading input until no more valid input can be read, or up +to the first byte which is not a white-space character, which remains +unread. +.P +A directive that is an ordinary character shall be executed as follows: +the next byte shall be read from the input and compared with the byte +that comprises the directive; if the comparison shows that they are not +equivalent, the directive shall fail, and the differing and subsequent +bytes shall remain unread. Similarly, if end-of-file, an encoding +error, or a read error prevents a character from being read, the +directive shall fail. +.P +A directive that is a conversion specification defines a set of +matching input sequences, as described below for each conversion +character. A conversion specification shall be executed in the +following steps. +.P +Input white-space characters (as specified by +.IR "\fIisspace\fR\^(\|)") +shall be skipped, unless the conversion specification includes a +.BR [ , +.BR c , +.BR C , +or +.BR n +conversion specifier. +.P +An item shall be read from the input, unless the conversion +specification includes an +.BR n +conversion specifier. An input item shall be defined as the longest +sequence of input bytes (up to any specified maximum field width, which +may be measured in characters or bytes dependent on the conversion +specifier) which is an initial subsequence of a matching sequence. The +first byte, if any, after the input item shall remain unread. If the +length of the input item is 0, the execution of the conversion +specification shall fail; this condition is a matching failure, unless +end-of-file, an encoding error, or a read error prevented input from +the stream, in which case it is an input failure. +.P +Except in the case of a +.BR % +conversion specifier, the input item (or, in the case of a +.BR %n +conversion specification, the count of input bytes) shall be converted +to a type appropriate to the conversion character. If the input item is +not a matching sequence, the execution of the conversion specification +fails; this condition is a matching failure. Unless assignment +suppression was indicated by a +.BR '*' , +the result of the conversion shall be placed in the object pointed to +by the first argument following the +.IR format +argument that has not already received a conversion result if the +conversion specification is introduced by +.BR % , +or in the +.IR n th +argument if introduced by the character sequence \fR"%\fIn\fR$"\fR. +If this object does not have an appropriate type, or if the result of +the conversion cannot be represented in the space provided, the +behavior is undefined. +.P +The +.BR %c , +.BR %s , +and +.BR %[ +conversion specifiers shall accept an optional assignment-allocation +character +.BR 'm' , +which shall cause a memory buffer to be allocated to hold the string +converted including a terminating null character. In such a case, +the argument corresponding to the conversion specifier should be a +reference to a pointer variable that will receive a pointer to the +allocated buffer. The system shall allocate a buffer as if +\fImalloc\fR() +had been called. The application shall be responsible for freeing the +memory after usage. If there is insufficient memory to allocate a buffer, +the function shall set +.IR errno +to +.BR [ENOMEM] +and a conversion error shall result. If the function returns EOF, any +memory successfully allocated for parameters using assignment-allocation +character +.BR 'm' +by this call shall be freed before the function returns. +.br +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "signed char" +or +.BR "unsigned char" . +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "short" +or +.BR "unsigned short" . +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long" +or +.BR "unsigned long" ; +that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR double ; +or that a following +.BR c , +.BR s , +or +.BR [ +conversion specifier applies to an argument with type pointer to +.BR wchar_t . +If the +.BR 'm' +assignment-allocation character is specified, the conversion applies +to an argument with the type pointer to a pointer to +.BR wchar_t . +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long long" +or +.BR "unsigned long long" . +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR intmax_t +or +.BR uintmax_t . +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR size_t +or the corresponding signed integer type. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR ptrdiff_t +or the corresponding +.BR unsigned +type. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR "long double" . +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The following conversion specifiers are valid: +.IP "\fRd\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIstrtol\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR int . +.IP "\fRi\fP" 8 +Matches an optionally signed integer, whose format is the same as +expected for the subject sequence of +\fIstrtol\fR() +with 0 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR int . +.IP "\fRo\fP" 8 +Matches an optionally signed octal integer, whose format is the same as +expected for the subject sequence of +\fIstrtoul\fR() +with the value 8 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRu\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIstrtoul\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRx\fP" 8 +Matches an optionally signed hexadecimal integer, whose format is the +same as expected for the subject sequence of +\fIstrtoul\fR() +with the value 16 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRa\fR,\ \fRe\fR,\ \fRf\fR,\ \fRg\fR" 8 +.br +Matches an optionally signed floating-point number, infinity, or NaN, +whose format is the same as expected for the subject sequence of +\fIstrtod\fR(). +In the absence of a size modifier, the application shall ensure that +the corresponding argument is a pointer to +.BR float . +.RS 8 +.P +If the +\fIfprintf\fR() +family of functions generates character string representations for +infinity and NaN (a symbolic entity encoded in floating-point +format) to support IEEE\ Std\ 754\(hy1985, the +\fIfscanf\fR() +family of functions shall recognize them as input. +.RE +.IP "\fRs\fP" 8 +Matches a sequence of bytes that are not white-space characters. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to the initial byte +of an array of +.BR char , +.BR "signed char" , +or +.BR "unsigned char" +large enough to accept the sequence and a terminating null character +code, which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the input is a sequence of characters that +begins in the initial shift state. Each character shall be converted to +a wide character as if by a call to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted. +If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null wide +character, which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RE +.IP "\fR[\fR" 8 +Matches a non-empty sequence of bytes from a set of expected bytes (the +.IR scanset ). +The normal skip over white-space characters shall be suppressed in this +case. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to the initial byte +of an array of +.BR char , +.BR "signed char" , +or +.BR "unsigned char" +large enough to accept the sequence and a terminating null byte, which +shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the input is a sequence of characters that +begins in the initial shift state. Each character in the sequence shall +be converted to a wide character as if by a call to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted. +If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null wide +character, which shall be added automatically. +.br +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.P +The conversion specification includes all subsequent bytes in the +.IR format +string up to and including the matching + +(\c +.BR ']' ). +The bytes between the square brackets (the +.IR scanlist ) +comprise the scanset, unless the byte after the + +is a + +(\c +.BR '\(ha' ), +in which case the scanset contains all bytes that do not appear in the +scanlist between the + +and the +. +If the conversion specification begins with +.BR \(dq[\|]\(dq +or +.BR \(dq[\(ha]\(dq , +the + +is included in the scanlist and the next + +is the matching + +that ends the conversion specification; otherwise, the first + +is the one that ends the conversion specification. If a +.BR '\-' +is in the scanlist and is not the first character, nor the second where +the first character is a +.BR '\(ha' , +nor the last character, the behavior is implementation-defined. +.RE +.IP "\fRc\fP" 8 +Matches a sequence of bytes of the number specified by the field width +(1 if no field width is present in the conversion specification). No +null byte is added. The normal skip over white-space characters +shall be suppressed in this case. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to the initial byte +of an array of +.BR char , +.BR "signed char" , +or +.BR "unsigned char" +large enough to accept the sequence. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the input shall be a sequence of characters +that begins in the initial shift state. Each character in the sequence +is converted to a wide character as if by a call to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted. +No null wide character is added. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the resulting sequence of wide characters. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RE +.IP "\fRp\fP" 8 +Matches an implementation-defined set of sequences, which shall be the +same as the set of sequences that is produced by the +.BR %p +conversion specification of the corresponding +\fIfprintf\fR() +functions. The application shall ensure that the corresponding argument +is a pointer to a pointer to +.BR void . +The interpretation of the input item is implementation-defined. If +the input item is a value converted earlier during the same program +execution, the pointer that results shall compare equal to that value; +otherwise, the behavior of the +.BR %p +conversion specification is undefined. +.IP "\fRn\fP" 8 +No input is consumed. The application shall ensure that the +corresponding argument is a pointer to the integer into which shall be +written the number of bytes read from the input so far by this call to +the +\fIfscanf\fR() +functions. Execution of a +.BR %n +conversion specification shall not increment the assignment count +returned at the completion of execution of the function. No argument +shall be converted, but one shall be consumed. If the conversion +specification includes an assignment-suppressing character or a field +width, the behavior is undefined. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Matches a single +.BR '%' +character; no conversion or assignment occurs. The complete conversion +specification shall be +.BR %% . +.P +If a conversion specification is invalid, the behavior is undefined. +.P +The conversion specifiers +.BR A , +.BR E , +.BR F , +.BR G , +and +.BR X +are also valid and shall be equivalent to +.BR a , +.BR e , +.BR f , +.BR g , +and +.BR x , +respectively. +.P +If end-of-file is encountered during input, conversion shall be +terminated. If end-of-file occurs before any bytes matching the current +conversion specification (except for +.BR %n ) +have been read (other than leading white-space characters, where +permitted), execution of the current conversion specification shall +terminate with an input failure. Otherwise, unless execution of the +current conversion specification is terminated with a matching failure, +execution of the following conversion specification (if any) shall be +terminated with an input failure. +.P +Reaching the end of the string in +\fIsscanf\fR() +shall be equivalent to encountering end-of-file for +\fIfscanf\fR(). +.P +If conversion terminates on a conflicting input, the offending input is +left unread in the input. Any trailing white space (including + +characters) shall be left unread unless matched by a conversion +specification. The success of literal matches and suppressed assignments +is only directly determinable via the +.BR %n +conversion specification. +.P +The +\fIfscanf\fR() +and +\fIscanf\fR() +functions may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be +marked for update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +\fIfscanf\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +successfully matched and assigned input items; this number can be zero +in the event of an early matching failure. If the input ends before the +first conversion (if any) has completed, and without a matching failure +having occurred, EOF shall be returned. If an error occurs before the +first conversion (if any) has completed, and without a matching failure +having occurred, EOF shall be returned +and +.IR errno +shall be set to indicate the error. +If a read error occurs, the error indicator for the stream shall be set. +.SH ERRORS +For the conditions under which the +\fIfscanf\fR() +functions fail and may fail, refer to +.IR "\fIfgetc\fR\^(\|)" +or +.IR "\fIfgetwc\fR\^(\|)". +.P +In addition, the +\fIfscanf\fR() +function shall fail if: +.TP +.BR EILSEQ +Input byte sequence does not form a valid character. +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +In addition, the +\fIfscanf\fR() +function may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The call: +.sp +.RS 4 +.nf + +int i, n; float x; char name[50]; +n = scanf("%d%f%s", &i, &x, name); +.fi +.P +.RE +.P +with the input line: +.sp +.RS 4 +.nf + +25 54.32E-1 Hamster +.fi +.P +.RE +.P +assigns to +.IR n +the value 3, to +.IR i +the value 25, to +.IR x +the value 5.432, and +.IR name +contains the string +.BR \(dqHamster\(dq . +.P +The call: +.sp +.RS 4 +.nf + +int i; float x; char name[50]; +(void) scanf("%2d%f%*d %[0123456789]", &i, &x, name); +.fi +.P +.RE +.P +with input: +.sp +.RS 4 +.nf + +56789 0123 56a72 +.fi +.P +.RE +.P +assigns 56 to +.IR i , +789.0 to +.IR x , +skips 0123, and places the string +.BR \(dq56\e0\(dq +in +.IR name . +The next call to +\fIgetchar\fR() +shall return the character +.BR 'a' . +.SS "Reading Data into an Array" +.P +The following call uses +\fIfscanf\fR() +to read three floating-point numbers from standard input into the +.IR input +array. +.sp +.RS 4 +.nf + +float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2); +.fi +.P +.RE +.SH "APPLICATION USAGE" +If the application calling +\fIfscanf\fR() +has any objects of type +.BR wint_t +or +.BR wchar_t , +it must also include the +.IR +header to have these objects defined. +.P +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIfscanf\fR(), +this is memory allocated via use of the +.BR 'm' +assignment-allocation character. +.SH RATIONALE +This function is aligned with the ISO/IEC\ 9899:\|1999 standard, and in doing so a few +``obvious'' things were not included. Specifically, the set of +characters allowed in a scanset is limited to single-byte characters. +In other similar places, multi-byte characters have been permitted, but +for alignment with the ISO/IEC\ 9899:\|1999 standard, it has not been done here. Applications +needing this could use the corresponding wide-character functions to +achieve the desired results. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)", +.IR "\fIstrtoul\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fseek.3p b/upstream/archlinux/man3p/fseek.3p new file mode 100644 index 00000000..82a8fab6 --- /dev/null +++ b/upstream/archlinux/man3p/fseek.3p @@ -0,0 +1,252 @@ +'\" et +.TH FSEEK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fseek, +fseeko +\(em reposition a file-position indicator in a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int fseek(FILE *\fIstream\fP, long \fIoffset\fP, int \fIwhence\fP); +int fseeko(FILE *\fIstream\fP, off_t \fIoffset\fP, int \fIwhence\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfseek\fR() +function shall set the file-position indicator for the stream pointed +to by +.IR stream . +If a read or write error occurs, the error indicator for the stream +shall be set and +\fIfseek\fR() +fails. +.P +The new position, measured in bytes from the beginning of the file, +shall be obtained by adding +.IR offset +to the position specified by +.IR whence . +The specified point is the beginning of the file for SEEK_SET, the +current value of the file-position indicator for SEEK_CUR, or +end-of-file for SEEK_END. +.P +If the stream is to be used with wide-character input/output functions, +the application shall ensure that +.IR offset +is either 0 or a value returned by an earlier call to +\fIftell\fR() +on the same stream and +.IR whence +is SEEK_SET. +.P +A successful call to +\fIfseek\fR() +shall clear the end-of-file indicator for the stream and undo any +effects of +\fIungetc\fR() +and +\fIungetwc\fR() +on the same stream. After an +\fIfseek\fR() +call, the next operation on an update stream may be either input or +output. +.P +If the most recent operation, other than +\fIftell\fR(), +on a given stream is +\fIfflush\fR(), +the file offset in the underlying open file description shall be +adjusted to reflect the location specified by +\fIfseek\fR(). +.P +The +\fIfseek\fR() +function shall allow the file-position indicator to be set beyond the +end of existing data in the file. If data is later written at this +point, subsequent reads of data in the gap shall return bytes with the +value 0 until data is actually written into the gap. +.P +The behavior of +\fIfseek\fR() +on devices which are incapable of seeking is implementation-defined. +The value of the file offset associated with such a device is +undefined. +.P +If the stream is writable and buffered data had not been written to the +underlying file, +\fIfseek\fR() +shall cause the unwritten data to be written to the file and shall mark +the last data modification and last file status change timestamps +of the file for update. +.P +In a locale with state-dependent encoding, whether +\fIfseek\fR() +restores the stream's shift state is implementation-defined. +.P +The +\fIfseeko\fR() +function shall be equivalent to the +\fIfseek\fR() +function except that the +.IR offset +argument is of type +.BR off_t . +.SH "RETURN VALUE" +The +\fIfseek\fR() +and +\fIfseeko\fR() +functions shall return 0 if they succeed. +.P +Otherwise, they shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfseek\fR() +and +\fIfseeko\fR() +functions shall fail if, +either the +.IR stream +is unbuffered or the +.IR stream 's +buffer needed to be flushed, and the call to +\fIfseek\fR() +or +\fIfseeko\fR() +causes an underlying +\fIlseek\fR() +or +\fIwrite\fR() +to be invoked, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the thread +would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying the stream file is not open for writing +or the stream's buffer needed to be flushed and the file is not open. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP +.BR EINVAL +The +.IR whence +argument is invalid. The resulting file-position indicator would be +set to a negative value. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to perform a +\fIwrite\fR() +to its controlling terminal, TOSTOP is set, the calling thread is not +blocking SIGTTOU, the process is not ignoring SIGTTOU, and the process +group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EOVERFLOW +For +\fIfseek\fR(), +the resulting file offset would be a value which cannot be represented +correctly in an object of type +.BR long . +.TP +.BR EOVERFLOW +For +\fIfseeko\fR(), +the resulting file offset would be a value which cannot be represented +correctly in an object of type +.BR off_t . +.TP +.BR EPIPE +An attempt was made to write to a pipe or FIFO that is not open for +reading by any process; a SIGPIPE +signal shall also be sent to the thread. +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.P +The +\fIfseek\fR() +and +\fIfseeko\fR() +functions may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fsetpos.3p b/upstream/archlinux/man3p/fsetpos.3p new file mode 100644 index 00000000..790fcb61 --- /dev/null +++ b/upstream/archlinux/man3p/fsetpos.3p @@ -0,0 +1,174 @@ +'\" et +.TH FSETPOS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fsetpos +\(em set current file position +.SH SYNOPSIS +.LP +.nf +#include +.P +int fsetpos(FILE *\fIstream\fP, const fpos_t *\fIpos\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfsetpos\fR() +function shall set the file position and state indicators for the +stream pointed to by +.IR stream +according to the value of the object pointed to by +.IR pos , +which the application shall ensure is a value obtained from an earlier +call to +\fIfgetpos\fR() +on the same stream. If a read or write error occurs, the error +indicator for the stream shall be set and +\fIfsetpos\fR() +fails. +.P +A successful call to the +\fIfsetpos\fR() +function shall clear the end-of-file indicator for the stream and +undo any effects of +\fIungetc\fR() +on the same stream. After an +\fIfsetpos\fR() +call, the next operation on an update stream may be either input or +output. +.P +The behavior of +\fIfsetpos\fR() +on devices which are incapable of seeking is implementation-defined. +The value of the file offset associated with such a device is +undefined. +.P +The +\fIfsetpos\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fIfsetpos\fR() +function shall return 0 if it succeeds; otherwise, it shall return +a non-zero value and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfsetpos\fR() +function shall fail if, +either the +.IR stream +is unbuffered or the +.IR stream 's +buffer needed to be flushed, and the call to +\fIfsetpos\fR() +causes an underlying +\fIlseek\fR() +or +\fIwrite\fR() +to be invoked, and: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set for the file descriptor and the thread +would be delayed in the write operation. +.TP +.BR EBADF +The file descriptor underlying the stream file is not open for writing +or the stream's buffer needed to be flushed and the file is not open. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the maximum file size. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the file size +limit of the process. +.TP +.BR EFBIG +The file is a regular file and an attempt was made to write at or +beyond the offset maximum associated with the corresponding stream. +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, +and no data was transferred. +.TP +.BR EIO +A physical I/O error has occurred, or the process is a member of a +background process group attempting to perform a +\fIwrite\fR() +to its controlling terminal, TOSTOP is set, the calling thread is not +blocking SIGTTOU, the process is not ignoring SIGTTOU, and the process +group of the process is orphaned. +This error may also be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR EPIPE +An attempt was made to write to a pipe or FIFO that is not open for +reading by any process; a SIGPIPE +signal shall also be sent to the thread. +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.P +The +\fIfsetpos\fR() +function may fail if: +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIftell\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fstat.3p b/upstream/archlinux/man3p/fstat.3p new file mode 100644 index 00000000..1b873b41 --- /dev/null +++ b/upstream/archlinux/man3p/fstat.3p @@ -0,0 +1,194 @@ +'\" et +.TH FSTAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fstat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +.P +int fstat(int \fIfildes\fP, struct stat *\fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIfstat\fR() +function shall obtain information about an open file associated with +the file descriptor +.IR fildes , +and shall write it to the area pointed to by +.IR buf . +.P +If +.IR fildes +references a shared memory object, the implementation shall update in +the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. +The implementation may update other fields and flags. +.P +If +.IR fildes +references a typed memory object, the implementation shall update in +the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. The implementation +may update other fields and flags. +.P +The +.IR buf +argument is a pointer to a +.BR stat +structure, as defined in +.IR , +into which information is placed concerning the file. +.P +For all other file types defined in this volume of POSIX.1\(hy2017, the structure members +.IR st_mode , +.IR st_ino , +.IR st_dev , +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_ctim , +and +.IR st_mtim +shall have meaningful values and the value of the +.IR st_nlink +member shall be set to the number of links to the file. +.P +An implementation that provides additional or alternative file access +control mechanisms may, under implementation-defined conditions, +cause +\fIfstat\fR() +to fail. +.P +The +\fIfstat\fR() +function shall update any time-related fields (as described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.9" ", " "File Times Update"), +before writing into the +.BR stat +structure. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIfstat\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EIO +An I/O error occurred while reading from the file system. +.TP +.BR EOVERFLOW +The file size in bytes or the number of blocks allocated to the file or +the file serial number cannot be represented correctly in the structure +pointed to by +.IR buf . +.P +The +\fIfstat\fR() +function may fail if: +.TP +.BR EOVERFLOW +One of the values is too large to store into the structure pointed to +by the +.IR buf +argument. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Obtaining File Status Information " +.P +The following example shows how to obtain file status information for a +file named +.BR /home/cnd/mod1 . +The structure variable +.IR buffer +is defined for the +.BR stat +structure. The +.BR /home/cnd/mod1 +file is opened with read/write privileges and is passed to the open +file descriptor +.IR fildes . +.sp +.RS 4 +.nf + +#include +#include +#include +.P +struct stat buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstat(fildes, &buffer); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfstatat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.9" ", " "File Times Update", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fstatat.3p b/upstream/archlinux/man3p/fstatat.3p new file mode 100644 index 00000000..8cd5f7f0 --- /dev/null +++ b/upstream/archlinux/man3p/fstatat.3p @@ -0,0 +1,481 @@ +'\" et +.TH FSTATAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fstatat, +lstat, +stat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fstatat(int fd, const char *restrict \fIpath\fP, + struct stat *restrict \fIbuf\fP, int \fIflag\fP); +int lstat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +int stat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIstat\fR() +function shall obtain information about the named file and write it +to the area pointed to by the +.IR buf +argument. The +.IR path +argument points to a pathname naming a file. Read, write, or execute +permission of the named file is not required. An implementation that +provides additional or alternate file access control mechanisms may, +under implementation-defined conditions, cause +\fIstat\fR() +to fail. In particular, the system may deny the existence of the file +specified by +.IR path . +.P +If the named file is a symbolic link, the +\fIstat\fR() +function shall continue pathname resolution using the contents of the +symbolic link, and shall return information pertaining to the resulting +file if the file exists. +.P +The +.IR buf +argument is a pointer to a +.BR stat +structure, as defined in the +.IR +header, into which information is placed concerning the file. +.P +The +\fIstat\fR() +function shall update any time-related fields (as described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.9" ", " "File Times Update"), +before writing into the +.BR stat +structure. +.P +If the named file is a shared memory object, the implementation +shall update in the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. The implementation may +update other fields and flags. +.P +If the named file is a typed memory object, the implementation +shall update in the +.BR stat +structure pointed to by the +.IR buf +argument the +.IR st_uid , +.IR st_gid , +.IR st_size , +and +.IR st_mode +fields, and only the S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and +S_IWOTH file permission bits need be valid. The implementation may +update other fields and flags. +.P +For all other file types defined in this volume of POSIX.1\(hy2017, the structure members +.IR st_mode , +.IR st_ino , +.IR st_dev , +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_ctim , +and +.IR st_mtim +shall have meaningful values and the value of the member +.IR st_nlink +shall be set to the number of links to the file. +.P +The +\fIlstat\fR() +function shall be equivalent to +\fIstat\fR(), +except when +.IR path +refers to a symbolic link. In that case +\fIlstat\fR() +shall return information about the link, while +\fIstat\fR() +shall return information about the file the link references. +.P +For symbolic links, the +.IR st_mode +member shall contain meaningful information when used with the file +type macros. The file mode bits in +.IR st_mode +are unspecified. The structure members +.IR st_ino , +.IR st_dev , +.IR st_uid , +.IR st_gid , +.IR st_atim , +.IR st_ctim , +and +.IR st_mtim +shall have meaningful values and the value of the +.IR st_nlink +member shall be set to the number of (hard) links to the symbolic link. +The value of the +.IR st_size +member shall be set to the length of the pathname contained in the +symbolic link not including any terminating null byte. +.P +The +\fIfstatat\fR() +function shall be equivalent to the +\fIstat\fR() +or +\fIlstat\fR() +function, depending on the value of +.IR flag +(see below), except in the case where +.IR path +specifies a relative path. In this case the status shall be retrieved +from a file relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches +are permitted using the current permissions of the directory +underlying the file descriptor. If the access mode is O_SEARCH, +the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, the status of the symbolic link is returned. +.P +If +\fIfstatat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIstat\fR() +or +\fIlstat\fR() +respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW bit +is set in +.IR flag . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix. +.TP +.BR EIO +An error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EOVERFLOW +The file size in bytes or the number of blocks allocated to the file or +the file serial number cannot be represented correctly in the structure +pointed to by +.IR buf . +.P +The +\fIfstatat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR EOVERFLOW +A value to be stored would overflow one of the members of the +.BR stat +structure. +.br +.P +The +\fIfstatat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Obtaining File Status Information" +.P +The following example shows how to obtain file status information for a +file named +.BR /home/cnd/mod1 . +The structure variable +.IR buffer +is defined for the +.BR stat +structure. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +struct stat buffer; +int status; +\&... +status = stat("/home/cnd/mod1", &buffer); +.fi +.P +.RE +.SS "Getting Directory Information" +.P +The following example fragment gets status information for each entry +in a directory. The call to the +\fIstat\fR() +function stores file information in the +.BR stat +structure pointed to by +.IR statbuf . +The lines that follow the +\fIstat\fR() +call format the fields in the +.BR stat +structure for presentation to the user of the program. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +.P +struct dirent *dp; +struct stat statbuf; +struct passwd *pwd; +struct group *grp; +struct tm *tm; +char datestring[256]; +\&... +/* Loop through directory entries. */ +while ((dp = readdir(dir)) != NULL) { +.P + /* Get entry\(aqs information. */ + if (stat(dp->d_name, &statbuf) == -1) + continue; +.P + /* Print out type, permissions, and number of links. */ + printf("%10.10s", sperm (statbuf.st_mode)); + printf("%4d", statbuf.st_nlink); +.P + /* Print out owner\(aqs name if it is found using getpwuid(). */ + if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); + else + printf(" %-8d", statbuf.st_uid); +.P + /* Print out group name if it is found using getgrgid(). */ + if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); + else + printf(" %-8d", statbuf.st_gid); +.P + /* Print size of file. */ + printf(" %9jd", (intmax_t)statbuf.st_size); +.P + tm = localtime(&statbuf.st_mtime); +.P + /* Get localized date string. */ + strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); +.P + printf(" %s %s\en", datestring, dp->d_name); +} +.fi +.P +.RE +.SS "Obtaining Symbolic Link Status Information" +.P +The following example shows how to obtain status information for a +symbolic link named +.BR /modules/pass1 . +The structure variable +.IR buffer +is defined for the +.BR stat +structure. If the +.IR path +argument specified the pathname for the file pointed to by the symbolic +link (\c +.BR /home/cnd/mod1 ), +the results of calling the function would be the same as those returned +by a call to the +\fIstat\fR() +function. +.sp +.RS 4 +.nf + +#include +.P +struct stat buffer; +int status; +\&... +status = lstat("/modules/pass1", &buffer); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The intent of the paragraph describing ``additional or alternate file +access control mechanisms'' is to allow a secure implementation where a +process +with a label that does not dominate the file's label cannot perform a +\fIstat\fR() +function. This is not related to read permission; a process with a +label that dominates the file's label does not need read permission. +An implementation that supports write-up operations could fail +\fIfstat\fR() +function calls even though it has a valid file descriptor open for +writing. +.P +The purpose of the +\fIfstatat\fR() +function is to obtain the status of files in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIstat\fR(), +resulting in unspecified behavior. By opening a file descriptor for the +target directory and using the +\fIfstatat\fR() +function it can be guaranteed that the file for which status is returned +is located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccess\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstat\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIreadlink\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.9" ", " "File Times Update", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fstatvfs.3p b/upstream/archlinux/man3p/fstatvfs.3p new file mode 100644 index 00000000..e2387e0f --- /dev/null +++ b/upstream/archlinux/man3p/fstatvfs.3p @@ -0,0 +1,235 @@ +'\" et +.TH FSTATVFS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fstatvfs, +statvfs +\(em get file system information +.SH SYNOPSIS +.LP +.nf +#include +.P +int fstatvfs(int \fIfildes\fP, struct statvfs *\fIbuf\fP); +int statvfs(const char *restrict \fIpath\fP, struct statvfs *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIfstatvfs\fR() +function shall obtain information about the file system containing +the file referenced by +.IR fildes . +.P +The +\fIstatvfs\fR() +function shall obtain information about the file system +containing the file named by +.IR path . +.P +For both functions, the +.IR buf +argument is a pointer to a +.BR statvfs +structure that shall be filled. Read, write, or execute permission of +the named file is not required. +.P +The following flags can be returned in the +.IR f_flag +member: +.IP ST_RDONLY 12 +Read-only file system. +.IP ST_NOSUID 12 +Setuid/setgid bits ignored by +.IR exec . +.P +It is unspecified whether all members of the +.BR statvfs +structure have meaningful values on all file systems. +.SH "RETURN VALUE" +Upon successful completion, +\fIstatvfs\fR() +shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIfstatvfs\fR() +and +\fIstatvfs\fR() +functions shall fail if: +.TP +.BR EIO +An I/O error occurred while reading the file system. +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR EOVERFLOW +One of the values to be returned cannot be represented correctly in +the structure pointed to by +.IR buf . +.P +The +\fIfstatvfs\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.P +The +\fIstatvfs\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIstatvfs\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Obtaining File System Information Using fstatvfs(\|)" +.P +The following example shows how to obtain file system information for +the file system upon which the file named +.BR /home/cnd/mod1 +resides, using the +\fIfstatvfs\fR() +function. The +.BR /home/cnd/mod1 +file is opened with read/write privileges and the open file descriptor +is passed to the +\fIfstatvfs\fR() +function. +.sp +.RS 4 +.nf + +#include +#include +.P +struct statvfs buffer; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = fstatvfs(fildes, &buffer); +.fi +.P +.RE +.SS "Obtaining File System Information Using statvfs(\|)" +.P +The following example shows how to obtain file system information for +the file system upon which the file named +.BR /home/cnd/mod1 +resides, using the +\fIstatvfs\fR() +function. +.sp +.RS 4 +.nf + +#include +.P +struct statvfs buffer; +int status; +\&... +status = statvfs("/home/cnd/mod1", &buffer); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIchown\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)", +.IR "\fIutime\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fsync.3p b/upstream/archlinux/man3p/fsync.3p new file mode 100644 index 00000000..a271e2ec --- /dev/null +++ b/upstream/archlinux/man3p/fsync.3p @@ -0,0 +1,154 @@ +'\" et +.TH FSYNC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fsync +\(em synchronize changes to a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int fsync(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIfsync\fR() +function shall request that all data for the open file descriptor +named by +.IR fildes +is to be transferred to the storage device associated with the file +described by +.IR fildes . +The nature of the transfer is implementation-defined. The +\fIfsync\fR() +function shall not return until the system has completed that action +or until an error is detected. +.P +If _POSIX_SYNCHRONIZED_IO is defined, the +\fIfsync\fR() +function shall force all currently queued I/O operations associated +with the file indicated by file descriptor +.IR fildes +to the synchronized I/O completion state. All I/O operations shall be +completed as defined for synchronized I/O file integrity completion. +.SH "RETURN VALUE" +Upon successful completion, +\fIfsync\fR() +shall return 0. Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. If the +\fIfsync\fR() +function fails, outstanding I/O operations are not guaranteed to have +been completed. +.SH ERRORS +The +\fIfsync\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid descriptor. +.TP +.BR EINTR +The +\fIfsync\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR fildes +argument does not refer to a file on which this operation is possible. +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.P +In the event that any of the queued I/O operations fail, +\fIfsync\fR() +shall return the error conditions defined for +\fIread\fR() +and +\fIwrite\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIfsync\fR() +function should be used by programs which require modifications to a +file to be completed before continuing; for example, a program which +contains a simple transaction facility might use it to ensure that all +modifications to a file or files caused by a transaction are recorded. +.SH RATIONALE +The +\fIfsync\fR() +function is intended to force a physical write of data from the buffer +cache, and to assure that after a system crash or other failure that +all data up to the time of the +\fIfsync\fR() +call is recorded on the disk. Since the concepts of ``buffer cache'', +``system crash'', ``physical write'', and ``non-volatile storage'' +are not defined here, the wording has to be more abstract. +.P +If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily on +the conformance document to tell the user what can be expected from the +system. It is explicitly intended that a null implementation is +permitted. This could be valid in the case where the system cannot +assure non-volatile storage under any circumstances or when the system +is highly fault-tolerant and the functionality is not required. In the +middle ground between these extremes, +\fIfsync\fR() +might or might not actually cause data to be written where it is safe +from a power failure. The conformance document should identify at least +that one configuration exists (and how to obtain that configuration) +where this can be assured for at least some files that the user can +select to use for critical data. It is not intended that an exhaustive +list is required, but rather sufficient information is provided so that +if critical data needs to be saved, the user can determine how the +system is to be configured to allow the data to be written to +non-volatile storage. +.P +It is reasonable to assert that the key aspects of +\fIfsync\fR() +are unreasonable to test in a test suite. That does not make the +function any less valuable, just more difficult to test. A formal +conformance test should probably force a system crash (power shutdown) +during the test for this condition, but it needs to be done in such a +way that automated testing does not require this to be done except when +a formal record of the results is being made. It would also not be +unreasonable to omit testing for +\fIfsync\fR(), +allowing it to be treated as a quality-of-implementation issue. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsync\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ftell.3p b/upstream/archlinux/man3p/ftell.3p new file mode 100644 index 00000000..dde6d166 --- /dev/null +++ b/upstream/archlinux/man3p/ftell.3p @@ -0,0 +1,131 @@ +'\" et +.TH FTELL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ftell, +ftello +\(em return a file offset in a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +long ftell(FILE *\fIstream\fP); +off_t ftello(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIftell\fR() +function shall obtain the current value of the file-position indicator +for the stream pointed to by +.IR stream . +.P +The +\fIftell\fR() +function shall not change the setting of +.IR errno +if successful. +.P +The +\fIftello\fR() +function shall be equivalent to +\fIftell\fR(), +except that the return value is of type +.BR off_t +and the +\fIftello\fR() +function may change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +Upon successful completion, +\fIftell\fR() +and +\fIftello\fR() +shall return the current value of the file-position indicator for the +stream measured in bytes from the beginning of the file. +.P +Otherwise, +\fIftell\fR() +and +\fIftello\fR() +shall return \-1, and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIftell\fR() +and +\fIftello\fR() +functions shall fail if: +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not an open file descriptor. +.TP +.BR EOVERFLOW +For +\fIftell\fR(), +the current file offset cannot be represented correctly in an object of +type +.BR long . +.TP +.BR EOVERFLOW +For +\fIftello\fR(), +the current file offset cannot be represented correctly in an object of +type +.BR off_t . +.TP +.BR ESPIPE +The file descriptor underlying +.IR stream +is associated with a pipe, FIFO, or socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetpos\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ftok.3p b/upstream/archlinux/man3p/ftok.3p new file mode 100644 index 00000000..b30ad2d0 --- /dev/null +++ b/upstream/archlinux/man3p/ftok.3p @@ -0,0 +1,195 @@ +'\" et +.TH FTOK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ftok +\(em generate an IPC key +.SH SYNOPSIS +.LP +.nf +#include +.P +key_t ftok(const char *\fIpath\fP, int \fIid\fP); +.fi +.SH DESCRIPTION +The +\fIftok\fR() +function shall return a key based on +.IR path +and +.IR id +that is usable in subsequent calls to +\fImsgget\fR(), +\fIsemget\fR(), +and +\fIshmget\fR(). +The application shall ensure that the +.IR path +argument is the pathname of an existing file that the process is +able to +\fIstat\fR(), +with the exception that if +\fIstat\fR() +would fail with +.BR [EOVERFLOW] +due to file size, +\fIftok\fR() +shall still succeed. +.P +The +\fIftok\fR() +function shall return the same key value for all paths that name the +same file, when called with the same +.IR id +value, and should return different key values when called with different +.IR id +values or with paths that name different files existing on the same +file system at the same time. It is unspecified whether +\fIftok\fR() +shall return the same key value when called again after the file named +by +.IR path +is removed and recreated with the same name. +.P +Only the low-order 8-bits of +.IR id +are significant. The behavior of +\fIftok\fR() +is unspecified if these bits are 0. +.SH "RETURN VALUE" +Upon successful completion, +\fIftok\fR() +shall return a key. Otherwise, +\fIftok\fR() +shall return (\fBkey_t\fP)\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIftok\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix. +.TP +.BR EIO +An error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.P +The +\fIftok\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting an IPC Key" +.P +The following example gets a key based on the pathname +.BR /tmp +and the ID value +.IR a . +It also assigns the value of the resulting key to the +.IR semkey +variable so that it will be available to a later call to +\fIsemget\fR(), +\fImsgget\fR(), +or +\fIshmget\fR(). +.sp +.RS 4 +.nf + +#include +\&... +key_t semkey; +.P +if ((semkey = ftok("/tmp", \(aqa\(aq)) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +For maximum portability, +.IR id +should be a single-byte character. +.P +Applications should not assume that the resulting key value is unique. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +Future versions of this standard may add new interfaces to provide +unique keys. +.SH "SEE ALSO" +.IR "\fImsgget\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ftruncate.3p b/upstream/archlinux/man3p/ftruncate.3p new file mode 100644 index 00000000..df85d15b --- /dev/null +++ b/upstream/archlinux/man3p/ftruncate.3p @@ -0,0 +1,163 @@ +'\" et +.TH FTRUNCATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ftruncate +\(em truncate a file to a specified length +.SH SYNOPSIS +.LP +.nf +#include +.P +int ftruncate(int \fIfildes\fP, off_t \fIlength\fP); +.fi +.SH DESCRIPTION +If +.IR fildes +is not a valid file descriptor open for writing, the +\fIftruncate\fR() +function shall fail. +.P +If +.IR fildes +refers to a regular file, the +\fIftruncate\fR() +function shall cause the size of the file to be truncated to +.IR length . +If the size of the file previously exceeded +.IR length , +the extra data shall no longer be available to reads on the file. If +the file previously was smaller than this size, +\fIftruncate\fR() +shall increase the size of the file. If the file size is increased, +the extended area shall appear as if it were zero-filled. The value of +the seek pointer shall not be modified by a call to +\fIftruncate\fR(). +.P +Upon successful completion, if +.IR fildes +refers to a regular file, +\fIftruncate\fR() +shall mark for update the last data modification and last file +status change timestamps of the file and the S_ISUID and S_ISGID bits +of the file mode may be cleared. If the +\fIftruncate\fR() +function is unsuccessful, the file is unaffected. +.P +If the request would cause the file size to exceed the soft file size +limit for the process, the request shall fail and the implementation +shall generate the SIGXFSZ signal for the thread. +.P +If +.IR fildes +refers to a directory, +\fIftruncate\fR() +shall fail. +.P +If +.IR fildes +refers to any other file type, except a shared memory object, the +result is unspecified. +.P +If +.IR fildes +refers to a shared memory object, +\fIftruncate\fR() +shall set the size of the shared memory object to +.IR length . +.P +If the effect of +\fIftruncate\fR() +is to decrease the size of a memory mapped file +or a shared memory object +and whole pages beyond the new end were previously mapped, then the +whole pages beyond the new end shall be discarded. +.P +References to discarded pages shall result in the generation of a +SIGBUS signal. +.P +If the effect of +\fIftruncate\fR() +is to increase the size of a memory object, it is unspecified +whether the contents of any mapped pages between the old end-of-file +and the new are flushed to the underlying object. +.SH "RETURN VALUE" +Upon successful completion, +\fIftruncate\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIftruncate\fR() +function shall fail if: +.TP +.BR EINTR +A signal was caught during execution. +.TP +.BR EINVAL +The +.IR length +argument was less than 0. +.TP +.BR EFBIG " or " EINVAL +.br +The +.IR length +argument was greater than the maximum file size. +.TP +.BR EFBIG +The file is a regular file and +.IR length +is greater than the offset maximum established in the open file +description associated with +.IR fildes . +.TP +.BR EIO +An I/O error occurred while reading from or writing to a file system. +.TP +.BR EBADF " or " EINVAL +.br +The +.IR fildes +argument is not a file descriptor open for writing. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)", +.IR "\fItruncate\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ftrylockfile.3p b/upstream/archlinux/man3p/ftrylockfile.3p new file mode 100644 index 00000000..4d84d939 --- /dev/null +++ b/upstream/archlinux/man3p/ftrylockfile.3p @@ -0,0 +1,40 @@ +'\" et +.TH FTRYLOCKFILE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ftrylockfile +\(em stdio locking functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int ftrylockfile(FILE *\fIfile\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIflockfile\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ftw.3p b/upstream/archlinux/man3p/ftw.3p new file mode 100644 index 00000000..b81f8c06 --- /dev/null +++ b/upstream/archlinux/man3p/ftw.3p @@ -0,0 +1,286 @@ +'\" et +.TH FTW "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ftw +\(em traverse (walk) a file tree +.SH SYNOPSIS +.LP +.nf +#include +.P +int ftw(const char *\fIpath\fP, int (*\fIfn\fP)(const char *, + const struct stat *\fIptr\fP, int \fIflag\fP), int \fIndirs\fP); +.fi +.SH DESCRIPTION +The +\fIftw\fR() +function shall recursively descend the directory hierarchy rooted in +.IR path . +For each object in the hierarchy, +\fIftw\fR() +shall call the function pointed to by +.IR fn , +passing it a pointer to a null-terminated character string containing +the name of the object, a pointer to a +.BR stat +structure containing information about the object, filled in as if +\fIstat\fR() +or +\fIlstat\fR() +had been called to retrieve the information. Possible values of the +integer, defined in the +.IR +header, are: +.IP FTW_D 10 +For a directory. +.IP FTW_DNR 10 +For a directory that cannot be read. +.IP FTW_F 10 +For a non-directory file. +.IP FTW_SL 10 +For a symbolic link (but see also FTW_NS below). +.IP FTW_NS 10 +For an object other than a symbolic link on which +\fIstat\fR() +could not successfully be executed. If the object is a symbolic link +and +\fIstat\fR() +failed, it is unspecified whether +\fIftw\fR() +passes FTW_SL or FTW_NS to the user-supplied function. +.P +If the integer is FTW_DNR, descendants of that directory shall not be +processed. If the integer is FTW_NS, the +.BR stat +structure contains undefined values. An example of an object that +would cause FTW_NS to be passed to the function pointed to by +.IR fn +would be a file in a directory with read but without execute (search) +permission. +.P +The +\fIftw\fR() +function shall visit a directory before visiting any of its +descendants. +.P +The +\fIftw\fR() +function shall use at most one file descriptor for each level in +the tree. +.P +The argument +.IR ndirs +should be in the range [1,\c +{OPEN_MAX}]. +.P +The tree traversal shall continue until either the tree is exhausted, +an invocation of +.IR fn +returns a non-zero value, or some error, other than +.BR [EACCES] , +is detected within +\fIftw\fR(). +.P +The +.IR ndirs +argument shall specify the maximum number of directory streams or file +descriptors or both available for use by +\fIftw\fR() +while traversing the tree. When +\fIftw\fR() +returns it shall close any directory streams and file descriptors it +uses not counting any opened by the application-supplied +.IR fn +function. +.P +The results are unspecified if the application-supplied +.IR fn +function does not preserve the current working directory. +.P +The +\fIftw\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If the tree is exhausted, +\fIftw\fR() +shall return 0. If the function pointed to by +.IR fn +returns a non-zero value, +\fIftw\fR() +shall stop its tree traversal and return whatever value was returned +by the function pointed to by +.IR fn . +If +\fIftw\fR() +detects an error, it shall return \-1 and set +.IR errno +to indicate the error. +.P +If +\fIftw\fR() +encounters an error other than +.BR [EACCES] +(see FTW_DNR and FTW_NS above), it shall return \-1 and set +.IR errno +to indicate the error. The external variable +.IR errno +may contain any error value that is possible when a directory is opened +or when one of the +.IR stat +functions is executed on a directory or file. +.SH ERRORS +The +\fIftw\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for any component of +.IR path +or read permission is denied for +.IR path . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of +.IR path +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EOVERFLOW +A field in the +.BR stat +structure cannot be represented correctly in the current programming +environment for one or more files found in the file hierarchy. +.P +The +\fIftw\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR ndirs +argument is invalid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +In addition, if the function pointed to by +.IR fn +encounters system errors, +.IR errno +may be set accordingly. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Walking a Directory Structure" +.P +The following example walks the current directory structure, calling +the +.IR fn +function for every directory entry, using at most 10 file descriptors: +.sp +.RS 4 +.nf + +#include +\&... +if (ftw(".", fn, 10) != 0) { + perror("ftw"); exit(2); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIftw\fR() +function may allocate dynamic storage during its operation. If +\fIftw\fR() +is forcibly terminated, such as by +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +being executed by the function pointed to by +.IR fn +or an interrupt routine, +\fIftw\fR() +does not have a chance to free that storage, so it remains +permanently allocated. A safe way to handle interrupts is to store the +fact that an interrupt has occurred, and arrange to have the function +pointed to by +.IR fn +return a non-zero value at its next invocation. +.P +Applications should use the +\fInftw\fR() +function instead of the obsolescent +\fIftw\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIftw\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fInftw\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/funlockfile.3p b/upstream/archlinux/man3p/funlockfile.3p new file mode 100644 index 00000000..2828c516 --- /dev/null +++ b/upstream/archlinux/man3p/funlockfile.3p @@ -0,0 +1,40 @@ +'\" et +.TH FUNLOCKFILE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +funlockfile +\(em stdio locking functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void funlockfile(FILE *\fIfile\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIflockfile\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/futimens.3p b/upstream/archlinux/man3p/futimens.3p new file mode 100644 index 00000000..8569303e --- /dev/null +++ b/upstream/archlinux/man3p/futimens.3p @@ -0,0 +1,393 @@ +'\" et +.TH FUTIMENS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +futimens, utimensat, utimes +\(em set file access and modification times +.SH SYNOPSIS +.LP +.nf +#include +.P +int futimens(int \fIfd\fP, const struct timespec \fItimes\fP[2]); +.P +#include +.P +int utimensat(int \fIfd\fP, const char *\fIpath\fP, const struct timespec \fItimes\fP[2], + int \fIflag\fP); +.P +#include +.P +int utimes(const char *\fIpath\fP, const struct timeval \fItimes\fP[2]); +.fi +.SH DESCRIPTION +The +\fIfutimens\fR() +and +\fIutimensat\fR() +functions shall set the access and modification times of a file +to the values of the +.IR times +argument. The +\fIfutimens\fR() +function changes the times of the file associated with the file +descriptor +.IR fd . +The +\fIutimensat\fR() +function changes the times of the file pointed to by the +.IR path +argument, relative to the directory associated with the file +descriptor +.IR fd . +Both functions allow time specifications accurate to the nanosecond. +.P +For +\fIfutimens\fR() +and +\fIutimensat\fR(), +the +.IR times +argument is an array of two +.BR timespec +structures. The first array member represents the date and time of +last access, and the second member represents the date and time of last +modification. The times in the +.BR timespec +structure are measured in seconds and nanoseconds since the Epoch. The +file's relevant timestamp shall be set to the greatest value supported +by the file system that is not greater than the specified time. +.P +If the +.IR tv_nsec +field of a +.BR timespec +structure has the special value UTIME_NOW, the file's relevant timestamp +shall be set to the greatest value supported by the file system that is +not greater than the current time. If the +.IR tv_nsec +field has the special value UTIME_OMIT, the file's relevant timestamp +shall not be changed. In either case, the +.IR tv_sec +field shall be ignored. +.P +If the +.IR times +argument is a null pointer, both the access and modification timestamps +shall be set to the greatest value supported by the file system that is +not greater than the current time. If +\fIutimensat\fR() +is passed a relative path in the +.IR path +argument, the file to be used shall be relative to the directory +associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of +the open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches +are permitted using the current permissions of the directory +underlying the file descriptor. If the access mode is O_SEARCH, +the function shall not perform the check. +.P +If +\fIutimensat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used. +.P +Only a process with the effective user ID equal to the user ID of the +file, or with write access to the file, or with appropriate privileges +may use +\fIfutimens\fR() +or +\fIutimensat\fR() +with a null pointer as the +.IR times +argument or with both +.IR tv_nsec +fields set to the special value UTIME_NOW. Only a process with the +effective user ID equal to the user ID of the file or with appropriate +privileges may use +\fIfutimens\fR() +or +\fIutimensat\fR() +with a non-null +.IR times +argument that does not have both +.IR tv_nsec +fields set to UTIME_NOW and does not have both +.IR tv_nsec +fields set to UTIME_OMIT. If both +.IR tv_nsec +fields are set to UTIME_OMIT, no ownership or permissions check shall be +performed for the file, but other error conditions may still be detected +(including +.BR [EACCES] +errors related to the path prefix). +.P +Values for the +.IR flag +argument of +\fIutimensat\fR() +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_NOFOLLOW 6 +.br +If +.IR path +names a symbolic link, then the access and modification times +of the symbolic link are changed. +.br +.P +Upon successful completion, +\fIfutimens\fR() +and +\fIutimensat\fR() +shall mark the last file status change timestamp for update, +with the exception that if both +.IR tv_nsec +fields are set to UTIME_OMIT, the file status change timestamp +need not be marked for update. +.P +The +\fIutimes\fR() +function shall be equivalent to the +\fIutimensat\fR() +function with the special value AT_FDCWD as the +.IR fd +argument and the +.IR flag +argument set to zero, except that the +.IR times +argument is a +.BR timeval +structure rather than a +.BR timespec +structure, and accuracy is only to the microsecond, not nanosecond, +and rounding towards the nearest second may occur. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, the file times shall +not be affected. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +The +.IR times +argument is a null pointer, or both +.IR tv_nsec +values are UTIME_NOW, and the effective user ID of the process +does not match the owner of the file and write access is denied. +.TP +.BR EINVAL +Either of the +.IR times +argument structures specified a +.IR tv_nsec +value that was neither UTIME_NOW nor UTIME_OMIT, and was a value less +than zero or greater than or equal to 1\|000 million. +.TP +.BR EINVAL +A new file timestamp would be a value whose +.IR tv_sec +component is not a value supported by the file system. +.TP +.BR EPERM +The +.IR times +argument is not a null pointer, does not have both +.IR tv_nsec +fields set to UTIME_NOW, does not have both +.IR tv_nsec +fields set to UTIME_OMIT, the calling process' effective user ID does +not match the owner of the file, and the calling process does not have +appropriate privileges. +.TP +.BR EROFS +The file system containing the file is read-only. +.P +The +\fIfutimens\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor. +.P +The +\fIutimensat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +The +\fIutimensat\fR() +and +\fIutimes\fR() +functions shall fail if: +.TP +.BR EACCES +Search permission is denied by a component of the path prefix. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.P +The +\fIutimensat\fR() +and +\fIutimes\fR() +functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +The +\fIutimensat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The purpose of the +\fIutimensat\fR() +function is to set the access and modification time of files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fIutimes\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIutimensat\fR() +function it can be guaranteed that the changed file is located relative +to the desired directory. +.P +The standard developers considered including a special case for the +permissions required by +\fIutimensat\fR() +when one +.IR tv_nsec +field is UTIME_NOW and the other is UTIME_OMIT. One possibility would +be to include this case in with the cases where +.IR times +is a null pointer or both fields are UTIME_NOW, where the call is allowed +if the process has write permission for the file. However, associating +write permission with an update to just the last data access timestamp +(which is normally updated by +\fIread\fR()) +did not seem appropriate. The other possibility would be to specify that +this one case is allowed if the process has read permission, but this +was felt to be too great a departure from the +\fIutime\fR() +and +\fIutimes\fR() +functions on which +\fIutimensat\fR() +is based. If an application needs to set the last data access timestamp +to the current time for a file on which it has read permission but is not +the owner, it can do so by opening the file, reading one or more bytes +(or reading a directory entry, if the file is a directory), and then +closing it. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIread\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fwide.3p b/upstream/archlinux/man3p/fwide.3p new file mode 100644 index 00000000..e3f17cdf --- /dev/null +++ b/upstream/archlinux/man3p/fwide.3p @@ -0,0 +1,109 @@ +'\" et +.TH FWIDE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fwide +\(em set stream orientation +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fwide(FILE *\fIstream\fP, int \fImode\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfwide\fR() +function shall determine the orientation of the stream pointed to by +.IR stream . +If +.IR mode +is greater than zero, the function first attempts to make the stream +wide-oriented. If +.IR mode +is less than zero, the function first attempts to make the stream +byte-oriented. Otherwise, +.IR mode +is zero and the function does not alter the orientation of the stream. +.P +If the orientation of the stream has already been determined, +\fIfwide\fR() +shall not change it. +.P +The +\fIfwide\fR() +function shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIfwide\fR(), +then check +.IR errno , +and if it is non-zero, assume an error has occurred. +.SH "RETURN VALUE" +The +\fIfwide\fR() +function shall return a value greater than zero if, after the call, the +stream has wide-orientation, a value less than zero if the stream has +byte-orientation, or zero if the stream has no orientation. +.SH ERRORS +The +\fIfwide\fR() +function may fail if: +.TP +.BR EBADF +The +.IR stream +argument is not a valid stream. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +A call to +\fIfwide\fR() +with +.IR mode +set to zero can be used to determine the current orientation of a +stream. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fwprintf.3p b/upstream/archlinux/man3p/fwprintf.3p new file mode 100644 index 00000000..94ef106d --- /dev/null +++ b/upstream/archlinux/man3p/fwprintf.3p @@ -0,0 +1,1045 @@ +'\" et +.TH FWPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fwprintf, +swprintf, +wprintf +\(em print formatted wide-character output +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fwprintf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, ...); +int swprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, ...); +int wprintf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfwprintf\fR() +function shall place output on the named output +.IR stream . +The +\fIwprintf\fR() +function shall place output on the standard output stream +.IR stdout . +The +\fIswprintf\fR() +function shall place output followed by the null wide character in +consecutive wide characters starting at *\fIws\fP; no more than +.IR n +wide characters shall be written, including a terminating null wide +character, which is always added (unless +.IR n +is zero). +.P +Each of these functions shall convert, format, and print its arguments +under control of the +.IR format +wide-character string. The +.IR format +is composed of zero or more directives: +.IR "ordinary wide-characters" , +which are simply copied to the output stream, and +.IR "conversion specifications" , +each of which results in the fetching of zero or more arguments. The +results are undefined if there are insufficient arguments for the +.IR format . +If the +.IR format +is exhausted while arguments remain, the excess arguments are evaluated +but are otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier wide character +.BR % +(see below) is replaced by the +sequence +.BR \(dq%n$\(dq , +where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}], +giving the position of the argument in the argument list. This feature +provides for the definition of +.IR format +wide-character strings that select arguments in an order appropriate to +specific languages (see the EXAMPLES section). +.P +The +.IR format +can contain either numbered argument specifications (that is, +\fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument +conversion specifications (that is, +.BR % +and +.BR * ), +but not both. The only exception to this is that +.BR %% +can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing +numbered and unnumbered argument specifications in a +.IR format +wide-character string are undefined. When numbered argument +specifications are used, specifying the +.IR N th +argument requires that all the leading arguments, from the first to the +(\fIN\fP\-1)th, are specified in the +.IR format +wide-character string. +.P +In +.IR format +wide-character strings containing the \fR"%\fIn\fR$"\fR form of +conversion specification, numbered arguments in the argument list can +be referenced from the +.IR format +wide-character string as many times as required. +.P +In +.IR format +wide-character strings containing the +.BR % +form of conversion specification, each argument in the argument list +shall be used exactly once. It is unspecified whether an encoding +error occurs if the format string contains +.BR wchar_t +values that do not correspond to members of the character +set of the current locale and the specified semantics do not +require that value to be processed by +\fIwcrtomb\fR(). +.P +All forms of the +\fIfwprintf\fR() +function allow for the insertion of a locale-dependent radix +character in the output string, output as a wide-character value. The +radix character is defined in the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.br +.P +Each conversion specification is introduced by the +.BR '%' +wide character +or by the wide-character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +Zero or more +.IR flags +(in any order), which modify the meaning of the conversion +specification. +.IP " *" 4 +An optional minimum +.IR "field width" . +If the converted value has fewer wide characters than the field width, +it shall be padded with + +characters by default on the left; it shall be padded on the right, +if the left-adjustment flag (\c +.BR '\-' ), +described below, is given to the field width. The field width takes the +form of an + +(\c +.BR '*' ), +described below, or a decimal integer. +.IP " *" 4 +An optional +.IR precision +that gives the minimum number of digits to appear for the +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers; the number of digits to appear after the radix +character for the +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +and +.BR F +conversion specifiers; the maximum number of significant digits for the +.BR g +and +.BR G +conversion specifiers; or the maximum number of wide characters to be +printed from a string in the +.BR s +conversion specifiers. The precision takes the form of a + +(\c +.BR '.' ) +followed either by an + +(\c +.BR '*' ), +described below, or an optional decimal digit string, where a null +digit string is treated as 0. If a precision appears with any other +conversion wide character, the behavior is undefined. +.IP " *" 4 +An optional length modifier that specifies the size of the argument. +.IP " *" 4 +A +.IR "conversion specifier" +wide character that indicates the type of conversion to be applied. +.P +A field width, or precision, or both, may be indicated by an + +(\c +.BR '*' ). +In this case an argument of type +.BR int +supplies the field width or precision. Applications shall ensure that +arguments specifying field width, or precision, or both appear in that +order before the argument, if any, to be converted. A negative field +width is taken as a +.BR '\-' +flag followed by a positive field width. A negative precision is taken +as if the precision were omitted. +In +.IR format +wide-character strings containing the \fR"%\fIn\fR$"\fR form +of a conversion specification, a field width or precision may be +indicated by the sequence \fR"*\fIm\fR$"\fR, where +.IR m +is a decimal integer in the range [1,{NL_ARGMAX}] giving the position +in the argument list (after the +.IR format +argument) of an integer argument containing the field width or +precision, for example: +.sp +.RS 4 +.nf + +wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); \*? +.fi +.P +.RE +.P +The flag wide characters and their meanings are: +.IP "\fR\(aq\fR" 8 +(The +.) +The integer portion of the result of a decimal conversion (\c +.BR %i , +.BR %d , +.BR %u , +.BR %f , +.BR %F , +.BR %g , +or +.BR %G ) +shall be formatted with thousands' grouping wide characters. For other +conversions, the behavior is undefined. The numeric grouping wide +character is used. +.IP "\fR\-\fR" 8 +The result of the conversion shall be left-justified within the field. +The conversion shall be right-justified if this flag is not specified. +.IP "\fR+\fR" 8 +The result of a signed conversion shall always begin with a sign (\c +.BR '+' +or +.BR '\-' ). +The conversion shall begin with a sign only when a negative value is +converted if this flag is not specified. +.IP 8 +If the first wide character of a signed conversion is not a sign, or if +a signed conversion results in no wide characters, a + +shall be prefixed to the result. This means that if the + +and +.BR '+' +flags both appear, the + +flag shall be ignored. +.IP "\fR#\fR" 8 +Specifies that the value is to be converted to an alternative form. +For +.BR o +conversion, it shall increase the precision, if and only if necessary, +to force the first digit of the result to be zero (if the value +and precision are both 0, a single 0 is printed). For +.BR x +or +.BR X +conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed +to it. For +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, the result shall always contain a radix +character, even if no digits follow it. Without this flag, a radix +character appears in the result of these conversions only if a digit +follows it. For +.BR g +and +.BR G +conversion specifiers, trailing zeros shall +.IR not +be removed from the result as they normally are. For other conversion +specifiers, the behavior is undefined. +.IP "\fR0\fR" 8 +For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, leading zeros (following any indication of sign +or base) are used to pad to the field width rather than performing +space padding, except when converting an infinity or NaN. If the +.BR '0' +and +.BR '\-' +flags both appear, the +.BR '0' +flag shall be ignored. For +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +and +.BR X +conversion specifiers, if a precision is specified, the +.BR '0' +flag shall be ignored. +If the +.BR '0' +and + +flags both appear, the grouping wide characters are inserted before +zero padding. For other conversions, the behavior is undefined. +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "signed char" +or +.BR "unsigned char" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "signed char" +or +.BR "unsigned char" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "signed char" +argument. +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "short" +or +.BR "unsigned short" +argument (the argument will have been promoted according to the integer +promotions, but its value shall be converted to +.BR "short" +or +.BR "unsigned short" +before printing); or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "short" +argument. +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long" +or +.BR "unsigned long" +argument; that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long" +argument; that a following +.BR c +conversion specifier applies to a +.BR wint_t +argument; that a following +.BR s +conversion specifier applies to a pointer to a +.BR wchar_t +argument; or has no effect on a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier. +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR "long long" +or +.BR "unsigned long long" +argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR "long long" +argument. +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to an +.BR intmax_t +or +.BR uintmax_t +argument; or that a following +.BR n +conversion specifier applies to a pointer to an +.BR intmax_t +argument. +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR size_t +or the corresponding signed integer type argument; or that a following +.BR n +conversion specifier applies to a pointer to a signed integer type +corresponding to a +.BR size_t +argument. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +or +.BR X +conversion specifier applies to a +.BR ptrdiff_t +or the corresponding +.BR unsigned +type argument; or that a following +.BR n +conversion specifier applies to a pointer to a +.BR ptrdiff_t +argument. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to a +.BR "long double" +argument. +.br +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The conversion specifiers and their meanings are: +.IP "\fRd\fR,\ \fRi\fR" 8 +The +.BR int +argument shall be converted to a signed decimal in the style +\fR"[\-]\fIdddd"\fR. The precision specifies the minimum number of +digits to appear; if the value being converted can be represented in +fewer digits, it shall be expanded with leading zeros. The default +precision shall be 1. The result of converting zero with an explicit +precision of zero shall be no wide characters. +.IP "\fRo\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned octal format in the style +.BR \(dqdddd\(dq . +The precision specifies the minimum number of digits to appear; if the +value being converted can be represented in fewer digits, it shall be +expanded with leading zeros. The default precision shall be 1. The +result of converting zero with an explicit precision of zero shall be +no wide characters. +.IP "\fRu\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned decimal format in the style +.BR \(dqdddd\(dq . +The precision specifies the minimum number of digits to appear; if the +value being converted can be represented in fewer digits, it shall be +expanded with leading zeros. The default precision shall be 1. The +result of converting zero with an explicit precision of zero shall be +no wide characters. +.IP "\fRx\fP" 8 +The +.BR unsigned +argument shall be converted to unsigned hexadecimal format in the style +.BR \(dqdddd\(dq ; +the letters +.BR \(dqabcdef\(dq +are used. The precision specifies the minimum number of digits to +appear; if the value being converted can be represented in fewer +digits, it shall be expanded with leading zeros. The default precision +shall be 1. The result of converting zero with an explicit precision of +zero shall be no wide characters. +.IP "\fRX\fP" 8 +Equivalent to the +.BR x +conversion specifier, except that letters +.BR \(dqABCDEF\(dq +are used instead of +.BR \(dqabcdef\(dq . +.IP "\fRf\fR,\ \fRF\fR" 8 +The +.BR double +argument shall be converted to decimal notation in the style +\fR"[\-]\fIddd.ddd"\fR, where the number of digits after the radix +character shall be equal to the precision specification. If the +precision is missing, it shall be taken as 6; if the precision is +explicitly zero and no +.BR '#' +flag is present, no radix character shall appear. If a radix character +appears, at least one digit shall appear before it. The value shall be +rounded in an implementation-defined manner to the appropriate number +of digits. +.RS 8 +.P +A +.BR double +argument representing an infinity shall be converted in one of the +styles +.BR \(dq[-]inf\(dq +or +.BR \(dq[-]infinity\(dq ; +which style is implementation-defined. A +.BR double +argument representing a NaN shall be converted in one of the styles +.BR \(dq[-]nan\(dq +or \fR"[\-]nan(\fIn-char-sequence\fR)"\fR; which style, and the +meaning of any \fIn-char-sequence\fR, is implementation-defined. The +.BR F +conversion specifier produces +.BR \(dqINF\(dq , +.BR \(dqINFINITY\(dq , +or +.BR \(dqNAN\(dq +instead of +.BR \(dqinf\(dq , +.BR \(dqinfinity\(dq , +or +.BR \(dqnan\(dq , +respectively. +.RE +.IP "\fRe\fR,\ \fRE\fR" 8 +The +.BR double +argument shall be converted in the style +\fR"[\-]\fId.ddd\fRe\fR\(+-dd"\fR, where there shall be one digit +before the radix character (which is non-zero if the argument is +non-zero) and the number of digits after it shall be equal to the +precision; if the precision is missing, it shall be taken as 6; if the +precision is zero and no +.BR '#' +flag is present, no radix character shall appear. The value shall be +rounded in an implementation-defined manner to the appropriate number +of digits. The +.BR E +conversion wide character shall produce a number with +.BR 'E' +instead of +.BR 'e' +introducing the exponent. The exponent shall always contain at least +two digits. If the value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRg\fR,\ \fRG\fR" 8 +The +.BR double +argument representing a floating-point number shall be converted in the +style +.BR f +or +.BR e +(or in the style +.BR F +or +.BR E +in the case of a +.BR G +conversion specifier), depending on the value converted and the precision. +Let +.BR P +equal the precision if non-zero, 6 if the precision is omitted, or 1 if the +precision is zero. Then, if a conversion with style +.BR E +would have an exponent of +.IR X : +.RS 8 +.IP -- 4 +If +.BR P >\c +.IR X \(>=\-4, +the conversion shall be with style +.BR f +(or +.BR F ) +and precision +.BR P \-(\c +.IR X +1). +.IP -- 4 +Otherwise, the conversion shall be with style +.BR e +(or +.BR E ) +and precision +.BR P \-1. +.P +Finally, unless the +.BR '#' +flag is used, any trailing zeros shall be removed from the fractional +portion of the result and the decimal-point character shall be removed +if there is no fractional portion remaining. +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRa\fR,\ \fRA\fR" 8 +A +.BR double +argument representing a floating-point number shall be converted in +the style \fR"[\-]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there +shall be one hexadecimal digit (which is non-zero if the argument is a +normalized floating-point number and is otherwise unspecified) before +the decimal-point wide character and the number of hexadecimal digits +after it shall be equal to the precision; if the precision is missing +and FLT_RADIX is a power of 2, then the precision shall be sufficient +for an exact representation of the value; if the precision is missing +and FLT_RADIX is not a power of 2, then the precision shall be sufficient +to distinguish values of type +.BR double , +except that trailing zeros may be omitted; if the precision is zero and +the +.BR '#' +flag is not specified, no decimal-point wide character shall appear. +The letters +.BR \(dqabcdef\(dq +are used for +.BR a +conversion and the letters +.BR \(dqABCDEF\(dq +for +.BR A +conversion. The +.BR A +conversion specifier produces a number with +.BR 'X' +and +.BR 'P' +instead of +.BR 'x' +and +.BR 'p' . +The exponent shall always contain at least one digit, and only as many +more digits as necessary to represent the decimal exponent of 2. If the +value is zero, the exponent shall be zero. +.RS 8 +.P +A +.BR double +argument representing an infinity or NaN shall be converted in the +style of an +.BR f +or +.BR F +conversion specifier. +.RE +.IP "\fRc\fP" 8 +If no +.BR l +(ell) qualifier is present, the +.BR int +argument shall be converted to a wide character as if by calling the +\fIbtowc\fR() +function and the resulting wide character shall be written. Otherwise, +the +.BR wint_t +argument shall be converted to +.BR wchar_t , +and written. +.IP "\fRs\fP" 8 +If no +.BR l +(ell) qualifier is present, the application shall ensure that the +argument is a pointer to a character array containing a character +sequence beginning in the initial shift state. Characters from the +array shall be converted as if by repeated calls to the +\fImbrtowc\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first character is converted, and +written up to (but not including) the terminating null wide character. +If the precision is specified, no more than that many wide characters +shall be written. If the precision is not specified, or is greater than +the size of the array, the application shall ensure that the array +contains a null wide character. +.RS 8 +.P +If an +.BR l +(ell) qualifier is present, the application shall ensure that the +argument is a pointer to an array of type +.BR wchar_t . +Wide characters from the array shall be written up to (but not +including) a terminating null wide character. If no precision is +specified, or is greater than the size of the array, the application +shall ensure that the array contains a null wide character. If a +precision is specified, no more than that many wide characters shall be +written. +.RE +.IP "\fRp\fP" 8 +The application shall ensure that the argument is a pointer to +.BR void . +The value of the pointer shall be converted to a sequence of printable +wide characters in an implementation-defined manner. +.IP "\fRn\fP" 8 +The application shall ensure that the argument is a pointer to an +integer into which is written the number of wide characters written to +the output so far by this call to one of the +\fIfwprintf\fR() +functions. No argument shall be converted, but one shall be consumed. +If the conversion specification includes any flags, a field width, or a +precision, the behavior is undefined. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Output a +.BR '%' +wide character; no argument shall be converted. The entire conversion +specification shall be +.BR %% . +.P +If a conversion specification does not match one of the above forms, +the behavior is undefined. +.P +In no case does a nonexistent or small field width cause truncation of +a field; if the result of a conversion is wider than the field width, +the field shall be expanded to contain the conversion result. +Characters generated by +\fIfwprintf\fR() +and +\fIwprintf\fR() +shall be printed as if +\fIfputwc\fR() +had been called. +.P +For +.BR a +and +.BR A +conversions, if FLT_RADIX is not a power of 2 and the result is not +exactly representable in the given precision, the result should be one +of the two adjacent numbers in hexadecimal floating style with the +given precision, with the extra stipulation that the error should have +a correct sign for the current rounding direction. +.P +For +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +and +.BR G +conversion specifiers, if the number of significant decimal digits is +at most DECIMAL_DIG, then the result should be correctly rounded. If +the number of significant decimal digits is more than DECIMAL_DIG but +the source value is exactly representable with DECIMAL_DIG digits, then +the result should be an exact representation with trailing zeros. +Otherwise, the source value is bounded by two adjacent decimal strings +.IR L +< +.IR U , +both having DECIMAL_DIG significant digits; the value of the resultant +decimal string +.IR D +should satisfy +.IR L +<= +.IR D +<= +.IR U , +with the extra stipulation that the error should have a correct sign +for the current rounding direction. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the call to a +successful execution of +\fIfwprintf\fR() +or +\fIwprintf\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream, or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +wide characters transmitted, excluding the terminating null wide character +in the case of +\fIswprintf\fR(), +or a negative value if an output error was encountered, +and set +.IR errno +to indicate the error. +.P +If +.IR n +or more wide characters were requested to be written, +\fIswprintf\fR() +shall return a negative value, +and set +.IR errno +to indicate the error. +.SH ERRORS +For the conditions under which +\fIfwprintf\fR() +and +\fIwprintf\fR() +fail and may fail, refer to +.IR "\fIfputwc\fR\^(\|)". +.P +In addition, all forms of +\fIfwprintf\fR() +shall fail if: +.TP +.BR EILSEQ +A wide-character code that does not correspond to a valid character has +been detected. +.P +In addition, +\fIfwprintf\fR() +and +\fIwprintf\fR() +may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +The +\fIswprintf\fR() +shall fail if: +.TP +.BR EOVERFLOW +The value of +.IR n +is greater than +{INT_MAX} +or the number of bytes needed to hold the output excluding the +terminating null is greater than +{INT_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +To print the language-independent date and time format, the following +statement could be used: +.sp +.RS 4 +.nf + +wprintf(format, weekday, month, day, hour, min); +.fi +.P +.RE +.P +For American usage, +.IR format +could be a pointer to the wide-character string: +.sp +.RS 4 +.nf + +L"%s, %s %d, %d:%.2d\en" +.fi +.P +.RE +.P +producing the message: +.sp +.RS 4 +.nf + +Sunday, July 3, 10:02 +.fi +.P +.RE +.P +whereas for German usage, +.IR format +could be a pointer to the wide-character string: +.sp +.RS 4 +.nf + +L"%1$s, %3$d. %2$s, %4$d:%5$.2d\en" +.fi +.P +.RE +.P +producing the message: +.sp +.RS 4 +.nf + +Sonntag, 3. Juli, 10:02 +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that there are insufficient +arguments for the format, it is recommended that the function +should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIbtowc\fR\^(\|)", +.IR "\fIfputwc\fR\^(\|)", +.IR "\fIfwscanf\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fwrite.3p b/upstream/archlinux/man3p/fwrite.3p new file mode 100644 index 00000000..3e79d48f --- /dev/null +++ b/upstream/archlinux/man3p/fwrite.3p @@ -0,0 +1,123 @@ +'\" et +.TH FWRITE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fwrite +\(em binary output +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t fwrite(const void *restrict \fIptr\fP, size_t \fIsize\fP, size_t \fInitems\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfwrite\fR() +function shall write, from the array pointed to by +.IR ptr , +up to +.IR nitems +elements whose size is specified by +.IR size , +to the stream pointed to by +.IR stream . +For each object, +.IR size +calls shall be made to the +\fIfputc\fR() +function, taking the values (in order) from an array of +.BR "unsigned char" +exactly overlaying the object. The file-position indicator for the +stream (if defined) shall be advanced by the number of bytes +successfully written. If an error occurs, the resulting value of the +file-position indicator for the stream is unspecified. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIfwrite\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream, or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +The +\fIfwrite\fR() +function shall return the number of elements successfully written, +which may be less than +.IR nitems +if a write error is encountered. If +.IR size +or +.IR nitems +is 0, +\fIfwrite\fR() +shall return 0 and the state of the stream remains unchanged. Otherwise, +if a write error occurs, the error indicator for the stream shall be set, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Because of possible differences in element length and byte ordering, +files written using +\fIfwrite\fR() +are application-dependent, and possibly cannot be read using +\fIfread\fR() +by a different application or by the same application on a different +processor. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/fwscanf.3p b/upstream/archlinux/man3p/fwscanf.3p new file mode 100644 index 00000000..1b256797 --- /dev/null +++ b/upstream/archlinux/man3p/fwscanf.3p @@ -0,0 +1,874 @@ +'\" et +.TH FWSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +fwscanf, +swscanf, +wscanf +\(em convert formatted wide-character input +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int fwscanf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, ...); +int swscanf(const wchar_t *restrict \fIws\fP, + const wchar_t *restrict \fIformat\fP, ...); +int wscanf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIfwscanf\fR() +function shall read from the named input +.IR stream . +The +\fIwscanf\fR() +function shall read from the standard input stream +.IR stdin . +The +\fIswscanf\fR() +function shall read from the wide-character string +.IR ws . +Each function reads wide characters, interprets them according to a +format, and stores the results in its arguments. Each expects, as +arguments, a control wide-character string +.IR format +described below, and a set of +.IR pointer +arguments indicating where the converted input should be stored. The +result is undefined if there are insufficient arguments for the +format. If the +.IR format +is exhausted while arguments remain, the excess arguments are +evaluated but are otherwise ignored. +.P +Conversions can be applied to the +.IR n th +argument after the +.IR format +in the argument list, rather than to the next unused argument. In this +case, the conversion specifier wide character +.BR % +(see below) is replaced by the sequence +.BR \(dq%n$\(dq , +where +.IR n +is a decimal integer in the range [1,{NL_ARGMAX}]. +This feature provides for the definition of +.IR format +wide-character strings that select arguments in an order appropriate +to specific languages. In +.IR format +wide-character strings containing the \fR"%\fIn\fR$"\fR form of +conversion specifications, +it is unspecified whether numbered arguments in the argument list can +be referenced from the +.IR format +wide-character string more than once. +.P +The +.IR format +can contain either form of a conversion specification\(emthat is, +.BR % +or \fR"%\fIn\fR$"\fR\(em but the two forms cannot normally be mixed +within a single +.IR format +wide-character string. The only exception to this is that +.BR %% +or +.BR %* +can be mixed with the \fR"%\fIn\fR$"\fR form. When numbered argument +specifications are used, specifying the +.IR N th +argument requires that all the leading arguments, from the first to +the (\c +.IR N \-1)th, +are pointers. +.P +The +\fIfwscanf\fR() +function in all its forms allows for detection of a language-dependent +radix character in the input string, encoded as a wide-character +value. The radix character is defined in the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +The +.IR format +is a wide-character string composed of zero or more directives. Each +directive is composed of one of the following: +one or more white-space wide characters (\c +, +, +, +, +or +); +an ordinary wide character (neither +.BR '%' +nor a white-space character); or a conversion specification. +It is unspecified whether an encoding error occurs if the +format string contains +.BR wchar_t +values that do not correspond to members of the character +set of the current locale and the specified semantics do not +require that value to be processed by +\fIwcrtomb\fR(). +.P +Each conversion specification is introduced by the +.BR '%' +or by the character sequence \fR"%\fIn\fR$"\fR, +after which the following appear in sequence: +.IP " *" 4 +An optional assignment-suppressing character +.BR '*' . +.IP " *" 4 +An optional non-zero decimal integer that specifies the maximum field +width. +.IP " *" 4 +An optional assignment-allocation character +.BR 'm' . +.IP " *" 4 +An optional length modifier that specifies the size of the receiving +object. +.IP " *" 4 +A conversion specifier wide character that specifies the type of +conversion to be applied. The valid conversion specifiers are described +below. +.P +The +\fIfwscanf\fR() +functions shall execute each directive of the format in turn. If a +directive fails, as detailed below, the function shall return. Failures +are described as input failures (due to the unavailability of input +bytes) or matching failures (due to inappropriate input). +.P +A directive composed of one or more white-space wide characters is +executed by reading input until no more valid input can be read, or up +to the first wide character which is not a white-space wide character, +which remains unread. +.P +A directive that is an ordinary wide character shall be executed as +follows. The next wide character is read from the input and compared +with the wide character that comprises the directive; if the comparison +shows that they are not equivalent, the directive shall fail, and the +differing and subsequent wide characters remain unread. Similarly, if +end-of-file, an encoding error, or a read error prevents a wide +character from being read, the directive shall fail. +.P +A directive that is a conversion specification defines a set of +matching input sequences, as described below for each conversion wide +character. A conversion specification is executed in the following +steps. +.P +Input white-space wide characters (as specified by +.IR "\fIiswspace\fR\^(\|)") +shall be skipped, unless the conversion specification includes a +.BR [ , +.BR c , +or +.BR n +conversion specifier. +.P +An item shall be read from the input, unless the conversion +specification includes an +.BR n +conversion specifier wide character. An input item is defined as the +longest sequence of input wide characters, not exceeding any specified +field width, which is an initial subsequence of a matching sequence. +The first wide character, if any, after the input item shall remain +unread. If the length of the input item is zero, the execution of the +conversion specification shall fail; this condition is a matching +failure, unless end-of-file, an encoding error, or a read error +prevented input from the stream, in which case it is an input failure. +.P +Except in the case of a +.BR % +conversion specifier, the input item (or, in the case of a +.BR %n +conversion specification, the count of input wide characters) shall be +converted to a type appropriate to the conversion wide character. If +the input item is not a matching sequence, the execution of the +conversion specification shall fail; this condition is a matching +failure. Unless assignment suppression was indicated by a +.BR '*' , +the result of the conversion shall be placed in the object pointed to +by the first argument following the +.IR format +argument that has not already received a conversion result if the +conversion specification is introduced by +.BR % , +or in the +.IR n th +argument if introduced by the wide-character sequence +\fR"%\fIn\fR$"\fR. +If this object does not have an appropriate type, or if the result +of the conversion cannot be represented in the space provided, the +behavior is undefined. +.P +The +.BR %c , +.BR %s , +and +.BR %[ +conversion specifiers shall accept an optional assignment-allocation +character +.BR 'm' , +which shall cause a memory buffer to be allocated to hold the +wide-character string converted including a terminating null wide +character. In such a case, the argument corresponding to the conversion +specifier should be a reference to a pointer value that will receive a +pointer to the allocated buffer. The system shall allocate a buffer as if +\fImalloc\fR() +had been called. The application shall be responsible for freeing the +memory after usage. If there is insufficient memory to allocate a buffer, +the function shall set +.IR errno +to +.BR [ENOMEM] +and a conversion error shall result. If the function returns EOF, any +memory successfully allocated for parameters using assignment-allocation +character +.BR 'm' +by this call shall be freed before the function returns. +.br +.P +The length modifiers and their meanings are: +.IP "\fRhh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "signed char" +or +.BR "unsigned char" . +.IP "\fRh\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "short" +or +.BR "unsigned short" . +.IP "\fRl\fR\ (ell)" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long" +or +.BR "unsigned long" ; +that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR double ; +or that a following +.BR c , +.BR s , +or +.BR [ +conversion specifier applies to an argument with type pointer to +.BR wchar_t . +If the +.BR 'm' +assignment-allocation character is specified, the conversion applies +to an argument with the type pointer to a pointer to +.BR wchar_t . +.IP "\fRll\fR\ (ell-ell)" 8 +.br +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR "long long" +or +.BR "unsigned long long" . +.IP "\fRj\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR intmax_t +or +.BR uintmax_t . +.IP "\fRz\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR size_t +or the corresponding signed integer type. +.IP "\fRt\fR" 8 +Specifies that a following +.BR d , +.BR i , +.BR o , +.BR u , +.BR x , +.BR X , +or +.BR n +conversion specifier applies to an argument with type pointer to +.BR ptrdiff_t +or the corresponding +.BR unsigned +type. +.IP "\fRL\fR" 8 +Specifies that a following +.BR a , +.BR A , +.BR e , +.BR E , +.BR f , +.BR F , +.BR g , +or +.BR G +conversion specifier applies to an argument with type pointer to +.BR "long double" . +.P +If a length modifier appears with any conversion specifier other than +as specified above, the behavior is undefined. +.P +The following conversion specifier wide characters are valid: +.IP "\fRd\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIwcstol\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall ensure +that the corresponding argument is a pointer to +.BR int . +.IP "\fRi\fP" 8 +Matches an optionally signed integer, whose format is the same as +expected for the subject sequence of +\fIwcstol\fR() +with 0 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR int . +.IP "\fRo\fP" 8 +Matches an optionally signed octal integer, whose format is the same as +expected for the subject sequence of +\fIwcstoul\fR() +with the value 8 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRu\fP" 8 +Matches an optionally signed decimal integer, whose format is the same +as expected for the subject sequence of +\fIwcstoul\fR() +with the value 10 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRx\fP" 8 +Matches an optionally signed hexadecimal integer, whose format is the +same as expected for the subject sequence of +\fIwcstoul\fR() +with the value 16 for the +.IR base +argument. In the absence of a size modifier, the application shall +ensure that the corresponding argument is a pointer to +.BR unsigned . +.IP "\fRa\fR,\ \fRe\fP,\ \fRf\fP,\ \fRg\fP" 8 +.br +Matches an optionally signed floating-point number, infinity, or NaN +whose format is the same as expected for the subject sequence of +\fIwcstod\fR(). +In the absence of a size modifier, the application shall ensure that +the corresponding argument is a pointer to +.BR float . +.RS 8 +.P +If the +\fIfwprintf\fR() +family of functions generates character string representations for +infinity and NaN (a symbolic entity encoded in floating-point +format) to support IEEE\ Std\ 754\(hy1985, the +\fIfwscanf\fR() +family of functions shall recognize them as input. +.RE +.IP "\fRs\fP" 8 +Matches a sequence of non-white-space wide characters. If no +.BR l +(ell) qualifier is present, characters from the input field shall be +converted as if by repeated calls to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to a character array +large enough to accept the sequence and the terminating null character, +which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RS 8 +.P +If the +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null wide +character, which shall be added automatically. +If the +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is present, the application shall +ensure that the corresponding argument is a pointer to a pointer +to a +.BR wchar_t . +.RE +.IP "\fR[\fR" 8 +Matches a non-empty sequence of wide characters from a set of expected +wide characters (the +.IR scanset ). +If no +.BR l +(ell) qualifier is present, wide characters from the input field shall +be converted as if by repeated calls to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted. If the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to a character array +large enough to accept the sequence and the terminating null character, +which shall be added automatically. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR wchar_t . +.RS 8 +.P +If an +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument is a pointer to an array of +.BR wchar_t +large enough to accept the sequence and the terminating null +wide character. +If an +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is specified, the application shall +ensure that the corresponding argument is a pointer to a pointer +to a +.BR wchar_t . +.P +The conversion specification includes all subsequent wide characters in +the +.IR format +string up to and including the matching + +(\c +.BR ']' ). +The wide characters between the square brackets (the +.IR scanlist ) +comprise the scanset, unless the wide character after the + +is a + +(\c +.BR '\(ha' ), +in which case the scanset contains all wide characters that do not +appear in the scanlist between the + +and the +. +If the conversion specification begins with +.BR \(dq[\|]\(dq +or +.BR \(dq[\(ha]\(dq , +the + +is included in the scanlist and the next + +is the matching + +that ends the conversion specification; otherwise, the first + +is the one that ends the conversion specification. If a +.BR '\-' +is in the scanlist and is not the first wide character, nor the second +where the first wide character is a +.BR '\(ha' , +nor the last wide character, the behavior is implementation-defined. +.RE +.IP "\fRc\fP" 8 +Matches a sequence of wide characters of exactly the number specified +by the field width (1 if no field width is present in the conversion +specification). +.RS 8 +.P +If no +.BR l +(ell) length modifier is present, characters from the input field shall +be converted as if by repeated calls to the +\fIwcrtomb\fR() +function, with the conversion state described by an +.BR mbstate_t +object initialized to zero before the first wide character is +converted. No null character is added. If the +.BR 'm' +assignment-allocation character is not specified, the application +shall ensure that the corresponding argument is a pointer to the +initial element of a character array large enough to accept the sequence. +Otherwise, the application shall ensure that the corresponding +argument is a pointer to a pointer to a +.BR char . +.P +No null wide character is added. If an +.BR l +(ell) length modifier is present and the +.BR 'm' +assignment-allocation character is not specified, the application shall +ensure that the corresponding argument shall be a pointer to the initial +element of an array of +.BR wchar_t +large enough to accept the sequence. +If an +.BR l +(ell) qualifier is present and the +.BR 'm' +assignment-allocation character is specified, the application shall +ensure that the corresponding argument is a pointer to a pointer +to a +.BR wchar_t . +.RE +.IP "\fRp\fP" 8 +Matches an implementation-defined set of sequences, which shall be +the same as the set of sequences that is produced by the +.BR %p +conversion specification of the corresponding +\fIfwprintf\fR() +functions. The application shall ensure that the corresponding argument +is a pointer to a pointer to +.BR void . +The interpretation of the input item is implementation-defined. If +the input item is a value converted earlier during the same program +execution, the pointer that results shall compare equal to that value; +otherwise, the behavior of the +.BR %p +conversion is undefined. +.IP "\fRn\fP" 8 +No input is consumed. The application shall ensure that the +corresponding argument is a pointer to the integer into which is to be +written the number of wide characters read from the input so far by +this call to the +\fIfwscanf\fR() +functions. Execution of a +.BR %n +conversion specification shall not increment the assignment count +returned at the completion of execution of the function. No argument +shall be converted, but one shall be consumed. If the conversion +specification includes an assignment-suppressing wide character or a +field width, the behavior is undefined. +.IP "\fRC\fP" 8 +Equivalent to +.BR lc . +.IP "\fRS\fP" 8 +Equivalent to +.BR ls . +.IP "\fR%\fR" 8 +Matches a single +.BR '%' +wide character; no conversion or assignment shall occur. The complete +conversion specification shall be +.BR %% . +.P +If a conversion specification is invalid, the behavior is undefined. +.P +The conversion specifiers +.BR A , +.BR E , +.BR F , +.BR G , +and +.BR X +are also valid and shall be equivalent to, respectively, +.BR a , +.BR e , +.BR f , +.BR g , +and +.BR x . +.P +If end-of-file is encountered during input, conversion is terminated. +If end-of-file occurs before any wide characters matching the current +conversion specification (except for +.BR %n ) +have been read (other than leading white-space, where permitted), +execution of the current conversion specification shall terminate with +an input failure. Otherwise, unless execution of the current conversion +specification is terminated with a matching failure, execution of the +following conversion specification (if any) shall be terminated with an +input failure. +.P +Reaching the end of the string in +\fIswscanf\fR() +shall be equivalent to encountering end-of-file for +\fIfwscanf\fR(). +.P +If conversion terminates on a conflicting input, the offending input +shall be left unread in the input. Any trailing white space (including +) +shall be left unread unless matched by a conversion specification. The +success of literal matches and suppressed assignments is only directly +determinable via the +.BR %n +conversion specification. +.P +The +\fIfwscanf\fR() +and +\fIwscanf\fR() +functions may mark the last data access timestamp of the file +associated with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetwc\fR(), +\fIfgetws\fR(), +\fIfwscanf\fR(), +\fIgetwc\fR(), +\fIgetwchar\fR(), +\fIvfwscanf\fR(), +\fIvwscanf\fR(), +or +\fIwscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetwc\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +successfully matched and assigned input items; this number can be zero +in the event of an early matching failure. If the input ends before +the first conversion (if any) has completed, and without a +matching failure having occurred, EOF shall be returned. If an +error occurs before the first conversion (if any) has completed, +and without a matching failure having occurred, EOF shall be returned +and +.IR errno +shall be set to indicate the error. +If a read error occurs, the error indicator for the stream shall be set. +.SH ERRORS +For the conditions under which the +\fIfwscanf\fR() +functions shall fail and may fail, refer to +.IR "\fIfgetwc\fR\^(\|)". +.P +In addition, the +\fIfwscanf\fR() +function shall fail if: +.TP +.BR EILSEQ +Input byte sequence does not form a valid character. +.TP +.BR ENOMEM +Insufficient storage space is available. +.P +In addition, the +\fIfwscanf\fR() +function may fail if: +.TP +.BR EINVAL +There are insufficient arguments. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The call: +.sp +.RS 4 +.nf + +int i, n; float x; char name[50]; +n = wscanf(L"%d%f%s", &i, &x, name); +.fi +.P +.RE +.P +with the input line: +.sp +.RS 4 +.nf + +25 54.32E-1 Hamster +.fi +.P +.RE +.P +assigns to +.IR n +the value 3, to +.IR i +the value 25, to +.IR x +the value 5.432, and +.IR name +contains the string +.BR \(dqHamster\(dq . +.P +The call: +.sp +.RS 4 +.nf + +int i; float x; char name[50]; +(void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name); +.fi +.P +.RE +.P +with input: +.sp +.RS 4 +.nf + +56789 0123 56a72 +.fi +.P +.RE +.P +assigns 56 to +.IR i , +789.0 to +.IR x , +skips 0123, and places the string +.BR \(dq56\e0\(dq +in +.IR name . +The next call to +\fIgetchar\fR() +shall return the character +.BR 'a' . +.SH "APPLICATION USAGE" +In format strings containing the +.BR '%' +form of conversion specifications, each argument in the argument +list is used exactly once. +.P +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIfwscanf\fR(), +this is memory allocated via use of the +.BR 'm' +assignment-allocation character. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIgetwc\fR\^(\|)", +.IR "\fIfwprintf\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)", +.IR "\fIwcstoul\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/gai_strerror.3p b/upstream/archlinux/man3p/gai_strerror.3p new file mode 100644 index 00000000..14731a5e --- /dev/null +++ b/upstream/archlinux/man3p/gai_strerror.3p @@ -0,0 +1,98 @@ +'\" et +.TH GAI_STRERROR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +gai_strerror +\(em address and name information error description +.SH SYNOPSIS +.LP +.nf +#include +.P +const char *gai_strerror(int \fIecode\fP); +.fi +.SH DESCRIPTION +The +\fIgai_strerror\fR() +function shall return a text string describing an error value for the +\fIgetaddrinfo\fR() +and +\fIgetnameinfo\fR() +functions listed in the +.IR +header. +.P +When the +.IR ecode +argument is one of the following values listed in the +.IR +header: +.TS +tab(!); +le le. +T{ +.nf +.BR [EAI_AGAIN] +.BR [EAI_BADFLAGS] +.BR [EAI_FAIL] +.BR [EAI_FAMILY] +.BR [EAI_MEMORY] +T}!T{ +.nf +.BR [EAI_NONAME] +.BR [EAI_OVERFLOW] +.BR [EAI_SERVICE] +.BR [EAI_SOCKTYPE] +.BR [EAI_SYSTEM] +.fi +T} +.TE +.P +the function return value shall point to a string describing the error. +If the argument is not one of those values, the function shall return a +pointer to a string whose contents indicate an unknown error. +.SH "RETURN VALUE" +Upon successful completion, +\fIgai_strerror\fR() +shall return a pointer to an implementation-defined string. +.SH "ERRORS" +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfreeaddrinfo\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getaddrinfo.3p b/upstream/archlinux/man3p/getaddrinfo.3p new file mode 100644 index 00000000..35420527 --- /dev/null +++ b/upstream/archlinux/man3p/getaddrinfo.3p @@ -0,0 +1,44 @@ +'\" et +.TH GETADDRINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getaddrinfo +\(em get address information +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int getaddrinfo(const char *restrict \fInodename\fP, + const char *restrict \fIservname\fP, + const struct addrinfo *restrict \fIhints\fP, + struct addrinfo **restrict \fIres\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfreeaddrinfo\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getc.3p b/upstream/archlinux/man3p/getc.3p new file mode 100644 index 00000000..a65d0a8e --- /dev/null +++ b/upstream/archlinux/man3p/getc.3p @@ -0,0 +1,92 @@ +'\" et +.TH GETC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getc +\(em get a byte from a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int getc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIgetc\fR() +function shall be equivalent to +.IR "\fIfgetc\fR\^(\|)", +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the integer value returned by +\fIgetc\fR() +is stored into a variable of type +.BR char +and then compared against the integer constant EOF, the comparison may +never succeed, because sign-extension of a variable of type +.BR char +on widening to integer is implementation-defined. +.P +Since it may be implemented as a macro, +\fIgetc\fR() +may treat incorrectly a +.IR stream +argument with side-effects. In particular, +.IR getc (* f \(pl\(pl) +does not necessarily work as expected. Therefore, use of this function +should be preceded by +.BR \(dq#undef getc\(dq +in such situations; +\fIfgetc\fR() +could also be used. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getc_unlocked.3p b/upstream/archlinux/man3p/getc_unlocked.3p new file mode 100644 index 00000000..271506ce --- /dev/null +++ b/upstream/archlinux/man3p/getc_unlocked.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETC_UNLOCKED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getc_unlocked, +getchar_unlocked, +putc_unlocked, +putchar_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int getc_unlocked(FILE *\fIstream\fP); +int getchar_unlocked(void); +int putc_unlocked(int \fIc\fP, FILE *\fIstream\fP); +int putchar_unlocked(int \fIc\fP); +.fi +.SH DESCRIPTION +Versions of the functions +\fIgetc\fR(), +\fIgetchar\fR(), +\fIputc\fR(), +and +\fIputchar\fR() +respectively named +\fIgetc_unlocked\fR(), +\fIgetchar_unlocked\fR(), +\fIputc_unlocked\fR(), +and +\fIputchar_unlocked\fR() +shall be provided which are functionally equivalent to the original +versions, with the exception that they are not required to be +implemented in a fully thread-safe manner. They shall be thread-safe +when used within a scope protected by +\fIflockfile\fR() +(or +\fIftrylockfile\fR()) +and +\fIfunlockfile\fR(). +These functions can safely be used in a multi-threaded program if and +only if they are called while the invoking thread owns the (\c +.BR "FILE *" ) +object, as is the case after a successful call to the +\fIflockfile\fR() +or +\fIftrylockfile\fR() +functions. +.P +If +\fIgetc_unlocked\fR() +or +\fIputc_unlocked\fR() +are implemented as macros they may evaluate +.IR stream +more than once, so the +.IR stream +argument should never be an expression with side-effects. +.SH "RETURN VALUE" +See +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +and +.IR "\fIputchar\fR\^(\|)". +.SH ERRORS +See +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +and +.IR "\fIputchar\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since they may be implemented as macros, +\fIgetc_unlocked\fR() +and +\fIputc_unlocked\fR() +may treat incorrectly a +.IR stream +argument with side-effects. In particular, \fIgetc_unlocked\fP(*f++) +and \fIputc_unlocked\fP(c,*f++) do not necessarily work as expected. +Therefore, use of these functions in such situations should be preceded +by the following statement as appropriate: +.sp +.RS 4 +.nf + +#undef getc_unlocked +#undef putc_unlocked +.fi +.P +.RE +.SH RATIONALE +Some I/O functions are typically implemented as macros for performance +reasons (for example, +\fIputc\fR() +and +\fIgetc\fR()). +For safety, they need to be synchronized, but it is often too expensive +to synchronize on every character. Nevertheless, it was felt that the +safety concerns were more important; consequently, the +\fIgetc\fR(), +\fIgetchar\fR(), +\fIputc\fR(), +and +\fIputchar\fR() +functions are required to be thread-safe. However, unlocked versions +are also provided with names that clearly indicate the unsafe nature of +their operation but can be used to exploit their higher performance. +These unlocked versions can be safely used only within explicitly +locked program regions, using exported locking primitives. In +particular, a sequence such as: +.sp +.RS 4 +.nf + +flockfile(fileptr); +putc_unlocked(\(aq1\(aq, fileptr); +putc_unlocked(\(aq\en\(aq, fileptr); +fprintf(fileptr, "Line 2\en"); +funlockfile(fileptr); +.fi +.P +.RE +.br +.P +is permissible, and results in the text sequence: +.sp +.RS 4 +.nf + +1 +Line 2 +.fi +.P +.RE +.P +being printed without being interspersed with output from other +threads. +.P +It would be wrong to have the standard names such as +\fIgetc\fR(), +\fIputc\fR(), +and so on, map to the ``faster, but unsafe'' rather than the ``slower, +but safe'' versions. In either case, you would still want to inspect +all uses of +\fIgetc\fR(), +\fIputc\fR(), +and so on, by hand when converting existing code. Choosing the safe +bindings as the default, at least, results in correct code and +maintains the ``atomicity at the function'' invariant. To do otherwise +would introduce gratuitous synchronization errors into converted code. +Other routines that modify the +.IR stdio +(\c +.BR "FILE *" ) +structures or buffers are also safely synchronized. +.P +Note that there is no need for functions of the form +\fIgetc_locked\fR(), +\fIputc_locked\fR(), +and so on, since this is the functionality of +\fIgetc\fR(), +\fIputc\fR(), +.IR "et al" . +It would be inappropriate to use a feature test macro to +switch a macro definition of +\fIgetc\fR() +between +\fIgetc_locked\fR() +and +\fIgetc_unlocked\fR(), +since the ISO\ C standard requires an actual function to exist, +a function whose behavior could not be changed by the +feature test macro. Also, providing both the +\fIxxx_locked\fR() +and +\fIxxx_unlocked\fR() +forms leads to the confusion of whether the suffix describes the +behavior of the function or the circumstances under which it should be +used. +.P +Three additional routines, +\fIflockfile\fR(), +\fIftrylockfile\fR(), +and +\fIfunlockfile\fR() +(which may be macros), are provided to allow the user to delineate a +sequence of I/O statements that are executed synchronously. +.P +The +\fIungetc\fR() +function is infrequently called relative to the other functions/macros +so no unlocked variation is needed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIflockfile\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgetchar\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputchar\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getchar.3p b/upstream/archlinux/man3p/getchar.3p new file mode 100644 index 00000000..94a43bcf --- /dev/null +++ b/upstream/archlinux/man3p/getchar.3p @@ -0,0 +1,76 @@ +'\" et +.TH GETCHAR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getchar +\(em get a byte from a +.IR stdin +stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int getchar(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIgetchar\fR() +function shall be equivalent to \fIgetc\fP(\fIstdin\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the integer value returned by +\fIgetchar\fR() +is stored into a variable of type +.BR char +and then compared against the integer constant EOF, the comparison may +never succeed, because sign-extension of a variable of type +.BR char +on widening to integer is implementation-defined. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIgetc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getchar_unlocked.3p b/upstream/archlinux/man3p/getchar_unlocked.3p new file mode 100644 index 00000000..113c599c --- /dev/null +++ b/upstream/archlinux/man3p/getchar_unlocked.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETCHAR_UNLOCKED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getchar_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int getchar_unlocked(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetc_unlocked\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getcwd.3p b/upstream/archlinux/man3p/getcwd.3p new file mode 100644 index 00000000..eb45b4c4 --- /dev/null +++ b/upstream/archlinux/man3p/getcwd.3p @@ -0,0 +1,294 @@ +'\" et +.TH GETCWD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getcwd +\(em get the pathname of the current working directory +.SH SYNOPSIS +.LP +.nf +#include +.P +char *getcwd(char *\fIbuf\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIgetcwd\fR() +function shall place an absolute pathname of the current working directory +in the array pointed to by +.IR buf , +and return +.IR buf . +The pathname shall contain no components that are dot or dot-dot, or +are symbolic links. +.P +If there are multiple pathnames that +\fIgetcwd\fR() +could place in the array pointed to by +.IR buf , +one beginning with a single + +character and one or more beginning with two + +characters, then +\fIgetcwd\fR() +shall place the pathname beginning with a single + +character in the array. The pathname shall not contain any unnecessary + +characters after the leading one or two + +characters. +.P +The +.IR size +argument is the size in bytes of the character array pointed to by the +.IR buf +argument. If +.IR buf +is a null pointer, the behavior of +\fIgetcwd\fR() +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetcwd\fR() +shall return the +.IR buf +argument. Otherwise, +\fIgetcwd\fR() +shall return a null pointer and set +.IR errno +to indicate the error. The contents of the array pointed to by +.IR buf +are then undefined. +.SH ERRORS +The +\fIgetcwd\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR size +argument is 0. +.TP +.BR ERANGE +The +.IR size +argument is greater than 0, but is smaller than the length of +the string +1. +.P +The +\fIgetcwd\fR() +function may fail if: +.TP +.BR EACCES +Search permission was denied for the current directory, or read or search +permission was denied for a directory above the current directory in +the file hierarchy. +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example uses +{PATH_MAX} +as the initial buffer size (unless it is indeterminate or very large), +and calls +\fIgetcwd\fR() +with progressively larger buffers until it does not give an +.BR [ERANGE] +error. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +\&... +.P +long path_max; +size_t size; +char *buf; +char *ptr; +.P +path_max = pathconf(".", _PC_PATH_MAX); +if (path_max == -1) + size = 1024; +else if (path_max > 10240) + size = 10240; +else + size = path_max; +.P +for (buf = ptr = NULL; ptr == NULL; size *= 2) +{ + if ((buf = realloc(buf, size)) == NULL) + { + ... handle error ... + } +.P + ptr = getcwd(buf, size); + if (ptr == NULL && errno != ERANGE) + { + ... handle error ... + } +} +\&... +free (buf); +.fi +.P +.RE +.SH "APPLICATION USAGE" +If the pathname obtained from +\fIgetcwd\fR() +is longer than +{PATH_MAX} +bytes, it could produce an +.BR [ENAMETOOLONG] +error if passed to +\fIchdir\fR(). +Therefore, in order to return to that directory it may be necessary to +break the pathname into sections shorter than +{PATH_MAX} +bytes and call +\fIchdir\fR() +on each section in turn (the first section being an absolute pathname and +subsequent sections being relative pathnames). A simpler way to handle +saving and restoring the working directory when it may be deeper than +{PATH_MAX} +bytes in the file hierarchy is to use a file descriptor and +\fIfchdir\fR(), +rather than +\fIgetcwd\fR() +and +\fIchdir\fR(). +However, the two methods do have some differences. The +\fIfchdir\fR() +approach causes the program to restore a working directory even +if it has been renamed in the meantime, whereas the +\fIchdir\fR() +approach restores to a directory with the same name as the original, +even if the directories were renamed in the meantime. Since the +\fIfchdir\fR() +approach does not access parent directories, it can succeed when +\fIgetcwd\fR() +would fail due to permissions problems. In applications conforming to +earlier versions of this standard, it was not possible to use the +\fIfchdir\fR() +approach when the working directory is searchable but not readable, +as the only way to open a directory was with O_RDONLY, whereas the +\fIgetcwd\fR() +approach can succeed in this case. +.SH RATIONALE +Having +\fIgetcwd\fR() +take no arguments and instead use the +\fImalloc\fR() +function to produce space for the returned argument was considered. +The advantage is that +\fIgetcwd\fR() +knows how big the working directory pathname is and can allocate an +appropriate amount of space. But the programmer would have to use the +\fIfree\fR() +function to free the resulting object, or each use of +\fIgetcwd\fR() +would further reduce the available memory. Finally, +\fIgetcwd\fR() +is taken from the SVID where it has the two arguments used in this volume of POSIX.1\(hy2017. +.P +The older function +.IR getwd (\|) +was rejected for use in this context because it had only a buffer +argument and no +.IR size +argument, and thus had no way to prevent overwriting the buffer, except +to depend on the programmer to provide a large enough buffer. +.P +On some implementations, if +.IR buf +is a null pointer, +\fIgetcwd\fR() +may obtain +.IR size +bytes of memory using +\fImalloc\fR(). +In this case, the pointer returned by +\fIgetcwd\fR() +may be used as the argument in a subsequent call to +\fIfree\fR(). +Invoking +\fIgetcwd\fR() +with +.IR buf +as a null pointer is not recommended in conforming applications. +.P +Earlier implementations of +\fIgetcwd\fR() +sometimes generated pathnames like +.BR \(dq../../../subdirname\(dq +internally, using them to explore the path of ancestor directories back +to the root. If one of these internal pathnames exceeded +{PATH_MAX} +in length, the implementation could fail with +.IR errno +set to +.BR [ENAMETOOLONG] . +This is no longer allowed. +.P +If a program is operating in a directory where some (grand)parent +directory does not permit reading, +\fIgetcwd\fR() +may fail, as in most implementations it must read the directory to +determine the name of the file. This can occur if search, but not read, +permission is granted in an intermediate directory, or if the program +is placed in that directory by some more privileged process (for +example, login). Including the +.BR [EACCES] +error condition makes the reporting of the error consistent and warns +the application developer that +\fIgetcwd\fR() +can fail for reasons beyond the control of the application developer or +user. Some implementations can avoid this occurrence (for example, by +implementing +\fIgetcwd\fR() +using +.IR pwd , +where +.IR pwd +is a set-user-root process), +thus the error was made optional. Since this volume of POSIX.1\(hy2017 permits the addition of +other errors, this would be a common addition and yet one that +applications could not be expected to deal with without this addition. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImalloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getdate.3p b/upstream/archlinux/man3p/getdate.3p new file mode 100644 index 00000000..ce2bdcf9 --- /dev/null +++ b/upstream/archlinux/man3p/getdate.3p @@ -0,0 +1,401 @@ +'\" et +.TH GETDATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getdate +\(em convert user format date and time +.SH SYNOPSIS +.LP +.nf +#include +.P +struct tm *getdate(const char *\fIstring\fP); +.fi +.SH DESCRIPTION +The +\fIgetdate\fR() +function shall convert a string representation of a date or time +into a broken-down time. +.P +The external variable or macro +.IR getdate_err , +which has type +.BR int , +is used by +\fIgetdate\fR() +to return error values. It is unspecified whether +.IR getdate_err +is a macro or an identifier declared with external linkage, and whether +or not it is a modifiable lvalue. If a macro definition is suppressed +in order to access an actual object, or a program defines an identifier +with the name +.IR getdate_err , +the behavior is undefined. +.P +Templates are used to parse and interpret the input string. The +templates are contained in a text file identified by the environment +variable +.IR DATEMSK . +The +.IR DATEMSK +variable should be set to indicate the full pathname of the file that +contains the templates. The first line in the template that matches +the input specification is used for interpretation and conversion into +the internal time format. +.P +The following conversion specifications shall be supported: +.IP "\fR%%\fR" 8 +Equivalent to +.BR % . +.IP "\fR%a\fR" 8 +Abbreviated weekday name. +.IP "\fR%A\fR" 8 +Full weekday name. +.IP "\fR%b\fR" 8 +Abbreviated month name. +.IP "\fR%B\fR" 8 +Full month name. +.IP "\fR%c\fR" 8 +Locale's appropriate date and time representation. +.IP "\fR%C\fR" 8 +Century number [00,99]; leading zeros are permitted but not required. +.IP "\fR%d\fR" 8 +Day of month [01,31]; the leading 0 is optional. +.IP "\fR%D\fR" 8 +Date as +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fR%e\fR" 8 +Equivalent to +.BR %d . +.IP "\fR%h\fR" 8 +Abbreviated month name. +.IP "\fR%H\fR" 8 +Hour [00,23]. +.IP "\fR%I\fR" 8 +Hour [01,12]. +.IP "\fR%m\fR" 8 +Month number [01,12]. +.IP "\fR%M\fR" 8 +Minute [00,59]. +.IP "\fR%n\fR" 8 +Equivalent to +. +.IP "\fR%p\fR" 8 +Locale's equivalent of either AM or PM. +.IP "\fR%r\fR" 8 +The locale's appropriate representation of time in AM and PM notation. +In the POSIX locale, this shall be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fR%R\fR" 8 +Time as +.BR %H :\c +.BR %M . +.IP "\fR%S\fR" 8 +Seconds [00,60]. The range goes to 60 (rather than stopping at 59) +to allow positive leap seconds to be expressed. Since leap seconds +cannot be predicted by any algorithm, leap second data must come from +some external source. +.IP "\fR%t\fR" 8 +Equivalent to +. +.IP "\fR%T\fR" 8 +Time as +.BR %H :\c +.BR %M :\c +.BR %S . +.IP "\fR%w\fR" 8 +Weekday number (Sunday = [0,6]). +.IP "\fR%x\fR" 8 +Locale's appropriate date representation. +.IP "\fR%X\fR" 8 +Locale's appropriate time representation. +.IP "\fR%y\fR" 8 +Year within century. When a century is not otherwise specified, values +in the range [69,99] shall refer to years 1969 to 1999 inclusive, +and values in the range [00,68] shall refer to years 2000 to 2068 +inclusive. +.RS 8 +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.RE +.IP "\fR%Y\fR" 8 +Year as +.BR \(dqccyy\(dq +(for example, 2001). +.IP "\fR%Z\fR" 8 +Timezone name or no characters if no timezone exists. If the +timezone supplied by +.BR %Z +is not the timezone that +\fIgetdate\fR() +expects, an invalid input specification error shall result. The +\fIgetdate\fR() +function calculates an expected timezone based on information supplied +to the function (such as the hour, day, and month). +.P +The match between the template and input specification performed by +\fIgetdate\fR() +shall be case-insensitive. +.P +The month and weekday names can consist of any combination of upper and +lowercase letters. The process can request that the input date or time +specification be in a specific language by setting the +.IR LC_TIME +category +(see +.IR "\fIsetlocale\fR\^(\|)"). +.P +Leading zeros are not necessary for the descriptors that allow leading +zeros. However, at most two digits are allowed for those descriptors, +including leading zeros. Extra white space in either the template file +or in +.IR string +shall be ignored. +.P +The results are undefined if the conversion specifications +.BR %c , +.BR %x , +and +.BR %X +include unsupported conversion specifications. +.P +The following rules apply for converting the input specification into +the internal format: +.IP " *" 4 +If +.BR %Z +is being scanned, then +\fIgetdate\fR() +shall initialize the broken-down time to be the current time in the +scanned timezone. Otherwise, it shall initialize the broken-down time +based on the current local time as if +\fIlocaltime\fR() +had been called. +.IP " *" 4 +If only the weekday is given, the day chosen shall be the day, starting +with today and moving into the future, which first matches the named +day. +.IP " *" 4 +If only the month (and no year) is given, the month chosen shall be the +month, starting with the current month and moving into the future, +which first matches the named month. The first day of the month shall +be assumed if no day is given. +.IP " *" 4 +If no hour, minute, and second are given, the current hour, minute, and +second shall be assumed. +.IP " *" 4 +If no date is given, the hour chosen shall be the hour, starting with +the current hour and moving into the future, which first matches the +named hour. +.P +If a conversion specification in the DATEMSK file does not correspond +to one of the conversion specifications above, the behavior is +unspecified. +.P +The +\fIgetdate\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetdate\fR() +shall return a pointer to a +.BR "struct tm" . +Otherwise, it shall return a null pointer and set +.IR getdate_err +to indicate the error. +.SH ERRORS +The +\fIgetdate\fR() +function shall fail in the following cases, setting +.IR getdate_err +to the value shown in the list below. Any changes to +.IR errno +are unspecified. +.IP " 1." 4 +The +.IR DATEMSK +environment variable is null or undefined. +.IP " 2." 4 +The template file cannot be opened for reading. +.IP " 3." 4 +Failed to get file status information. +.IP " 4." 4 +The template file is not a regular file. +.IP " 5." 4 +An I/O error is encountered while reading the template file. +.IP " 6." 4 +Memory allocation failed (not enough memory available). +.IP " 7." 4 +There is no line in the template that matches the input. +.IP " 8." 4 +Invalid input specification. For example, February 31; or a time is +specified that cannot be represented in a +.BR time_t +(representing the time in seconds since the Epoch). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.IP " 1." 4 +The following example shows the possible contents of a template: +.RS 4 +.sp +.RS 4 +.nf + +%m +%A %B %d, %Y, %H:%M:%S +%A +%B +%m/%d/%y %I %p +%d,%m,%Y %H:%M +at %A the %dst of %B in %Y +run job at %I %p,%B %dnd +%A den %d. %B %Y %H.%M Uhr +.fi +.P +.RE +.RE +.IP " 2." 4 +The following are examples of valid input specifications for the +template in Example 1: +.RS 4 +.sp +.RS 4 +.nf + +getdate("10/1/87 4 PM"); +getdate("Friday"); +getdate("Friday September 18, 1987, 10:30:30"); +getdate("24,9,1986 10:30"); +getdate("at monday the 1st of december in 1986"); +getdate("run job at 3 PM, december 2nd"); +.fi +.P +.RE +.P +If the +.IR LC_TIME +category is set to a German locale that includes +.IR freitag +as a weekday name and +.IR oktober +as a month name, the following would be valid: +.sp +.RS 4 +.nf + +getdate("freitag den 10. oktober 1986 10.30 Uhr"); +.fi +.P +.RE +.RE +.IP " 3." 4 +The following example shows how local date and time specification can +be defined in the template: +.TS +box tab(!) center; +cB | cB +lf5 | lf5. +Invocation!Line in Template +_ +getdate("11/27/86")!%m/%d/%y +getdate("27.11.86")!%d.%m.%y +getdate("86-11-27")!%y-%m-%d +getdate("Friday 12:00:00")!%A %H:%M:%S +.TE +.IP " 4." 4 +The following examples help to illustrate the above rules assuming that +the current date is Mon Sep 22 12:19:47 EDT 1986 and the +.IR LC_TIME +category is set to the default C or POSIX locale: +.TS +box tab(!) center; +cB | cB | cB +lf5 | lf5 | l. +Input!Line in Template!Date +_ +Mon!%a!Mon Sep 22 12:19:47 EDT 1986 +Sun!%a!Sun Sep 28 12:19:47 EDT 1986 +Fri!%a!Fri Sep 26 12:19:47 EDT 1986 +September!%B!Mon Sep 1 12:19:47 EDT 1986 +January!%B!Thu Jan 1 12:19:47 EST 1987 +December!%B!Mon Dec 1 12:19:47 EST 1986 +Sep Mon!%b %a!Mon Sep 1 12:19:47 EDT 1986 +Jan Fri!%b %a!Fri Jan 2 12:19:47 EST 1987 +Dec Mon!%b %a!Mon Dec 1 12:19:47 EST 1986 +Jan Wed 1989!%b %a %Y!Wed Jan 4 12:19:47 EST 1989 +Fri 9!%a %H!Fri Sep 26 09:00:00 EDT 1986 +Feb 10:30!%b %H:%S!Sun Feb 1 10:00:30 EST 1987 +10:30!%H:%M!Tue Sep 23 10:30:00 EDT 1986 +13:30!%H:%M!Mon Sep 22 13:30:00 EDT 1986 +.TE +.SH "APPLICATION USAGE" +Although historical versions of +\fIgetdate\fR() +did not require that +.IR +declare the external variable +.IR getdate_err , +this volume of POSIX.1\(hy2017 does require it. The standard developers encourage applications +to remove declarations of +.IR getdate_err +and instead incorporate the declaration by including +.IR . +.P +Applications should use +.BR %Y +(4-digit years) in preference to +.BR %y +(2-digit years). +.SH RATIONALE +In standard locales, the conversion specifications +.BR %c , +.BR %x , +and +.BR %X +do not include unsupported conversion specifiers and so the text +regarding results being undefined is not a problem in that case. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fItimes\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getdelim.3p b/upstream/archlinux/man3p/getdelim.3p new file mode 100644 index 00000000..36409948 --- /dev/null +++ b/upstream/archlinux/man3p/getdelim.3p @@ -0,0 +1,235 @@ +'\" et +.TH GETDELIM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getdelim, getline +\(em read a delimited record from +.IR stream +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t getdelim(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + int \fIdelimiter\fP, FILE *restrict \fIstream\fP); +ssize_t getline(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIgetdelim\fR() +function shall read from +.IR stream +until it encounters a character matching the +.IR delimiter +character. The +.IR delimiter +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +of equal value that terminates the read process. If the +.IR delimiter +argument has any other value, the behavior is undefined. +.P +The application shall ensure that +.IR *lineptr +is a valid argument that could be passed to the +\fIfree\fR() +function. If +.IR *n +is non-zero, the application shall ensure that +.IR *lineptr +either points to an object of size at least +.IR *n +bytes, or is a null pointer. +.P +If +.IR *lineptr +is a null pointer or if the object pointed to by +.IR *lineptr +is of insufficient size, an object shall be allocated as if by +\fImalloc\fR() +or the object shall be reallocated as if by +\fIrealloc\fR(), +respectively, such that the object is large enough to hold +the characters to be written to it, including the terminating NUL, +and +.IR *n +shall be set to the new size. If the object was allocated, +or if the reallocation operation moved the object, +.IR *lineptr +shall be updated to point to the new object or new location. +The characters read, including any delimiter, shall be stored +in the object, and a terminating NUL added when the delimiter +or end-of-file is encountered. +.P +The +\fIgetline\fR() +function shall be equivalent to the +\fIgetdelim\fR() +function with the +.IR delimiter +character equal to the + +character. +.P +The +\fIgetdelim\fR() +and +\fIgetline\fR() +functions may mark the last data access timestamp of the file associated +with +.IR stream +for update. The last data access timestamp shall be marked for update +by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fIgetline\fR() +and +\fIgetdelim\fR() +functions shall return the number of bytes written into the buffer, +including the delimiter character if one was encountered before EOF, +but excluding the terminating NUL character. If the end-of-file +indicator for the stream is set, or if no characters were read and the +stream is at end-of-file, the end-of-file indicator for the +stream shall be set and the function shall return \-1. +If an error occurs, the error indicator for the stream shall be set, +and the function shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +For the conditions under which the +\fIgetdelim\fR() +and +\fIgetline\fR() +functions shall fail and may fail, refer to +.IR "\fIfgetc\fR\^(\|)". +.P +In addition, these functions shall fail if: +.TP +.BR EINVAL +.IR lineptr +or +.IR n +is a null pointer. +.TP +.BR ENOMEM +Insufficient memory is available. +.br +.P +These functions may fail if: +.TP +.BR EOVERFLOW +The number of bytes to be written into the buffer, including the +delimiter character (if encountered), would exceed +{SSIZE_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf + +#include +#include +.P +int main(void) +{ + FILE *fp; + char *line = NULL; + size_t len = 0; + ssize_t read; + fp = fopen("/etc/motd", "r"); + if (fp == NULL) + exit(1); + while ((read = getline(&line, &len, fp)) != -1) { + printf("Retrieved line of length %zu :\en", read); + printf("%s", line); + } + if (ferror(fp)) { + /* handle error */ + } + free(line); + fclose(fp); + return 0; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +Setting +.IR *lineptr +to a null pointer and +.IR *n +to zero are allowed and a recommended way to start parsing a file. +.P +The +\fIferror\fR() +or +\fIfeof\fR() +functions should be used to distinguish between an error condition and +an end-of-file condition. +.P +Although a NUL terminator is always supplied after the line, note that +.IR strlen (* lineptr ) +will be smaller than the return value if the line contains embedded +NUL characters. +.SH RATIONALE +These functions are widely used to solve the problem that the +\fIfgets\fR() +function has with long lines. The functions automatically enlarge the +target buffers if needed. These are especially useful since they reduce +code needed for applications. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetc\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getegid.3p b/upstream/archlinux/man3p/getegid.3p new file mode 100644 index 00000000..1a7bb56f --- /dev/null +++ b/upstream/archlinux/man3p/getegid.3p @@ -0,0 +1,86 @@ +'\" et +.TH GETEGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getegid +\(em get the effective group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +gid_t getegid(void); +.fi +.SH DESCRIPTION +The +\fIgetegid\fR() +function shall return the effective group ID of the calling process. +The +\fIgetegid\fR() +function shall not modify +.IR errno . +.SH "RETURN VALUE" +The +\fIgetegid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +In a conforming environment, +\fIgetegid\fR() +will always succeed. It is possible for implementations to provide +an extension where a process in a non-conforming environment will +not be associated with a user or group ID. It is recommended that such +implementations return (\c +.BR gid_t )\-1 +and set +.IR errno +to indicate such an environment; doing so does not violate +this standard, since such an environment is already an extension. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getenv.3p b/upstream/archlinux/man3p/getenv.3p new file mode 100644 index 00000000..d7ea8580 --- /dev/null +++ b/upstream/archlinux/man3p/getenv.3p @@ -0,0 +1,226 @@ +'\" et +.TH GETENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getenv +\(em get value of an environment variable +.SH SYNOPSIS +.LP +.nf +#include +.P +char *getenv(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIgetenv\fR() +function shall search the environment of the calling process (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables") +for the environment variable +.IR name +if it exists and return a pointer to the value of the environment +variable. If the specified environment variable cannot be found, a null +pointer shall be returned. The application shall ensure that it does +not modify the string pointed to by the +\fIgetenv\fR() +function. +.P +The returned string pointer might be invalidated or +the string content might be overwritten by a subsequent call to +\fIgetenv\fR(), +\fIsetenv\fR(), +\fIunsetenv\fR(), +.br +or (if supported) +\fIputenv\fR() +but they shall not be affected by a call to any other function in this volume of POSIX.1\(hy2017. +.P +The returned string pointer might also be invalidated if the calling +thread is terminated. +.P +The +\fIgetenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetenv\fR() +shall return a pointer to a string containing the +.IR value +for the specified +.IR name . +If the specified +.IR name +cannot be found in the environment of the calling process, a null +pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Value of an Environment Variable" +.P +The following example gets the value of the +.IR HOME +environment variable. +.sp +.RS 4 +.nf + +#include +\&... +const char *name = "HOME"; +char *value; +.P +value = getenv(name); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIclearenv\fR() +function was considered but rejected. The +\fIputenv\fR() +function has now been included for alignment with the Single UNIX +Specification. +.P +The +\fIgetenv\fR() +function is inherently not thread-safe because it returns a value +pointing to static data. +.P +Conforming applications are required not to directly modify the pointers +to which +.IR environ +points, but to use only the +\fIsetenv\fR(), +\fIunsetenv\fR(), +and +\fIputenv\fR() +functions, or assignment to +.IR environ +itself, to manipulate the process environment. This constraint allows +the implementation to properly manage the memory it allocates. This +enables the implementation to free any space it has allocated to strings +(and perhaps the pointers to them) stored in +.IR environ +when +\fIunsetenv\fR() +is called. A C runtime start-up procedure (that which invokes +\fImain\fR() +and perhaps initializes +.IR environ ) +can also initialize a flag indicating that none of the environment has +yet been copied to allocated storage, or that the separate table has +not yet been initialized. If the application switches to a complete new +environment by assigning a new value to +.IR environ , +this can be detected by +\fIgetenv\fR(), +\fIsetenv\fR(), +\fIunsetenv\fR(), +or +\fIputenv\fR() +and the implementation can at that point reinitialize based on the new +environment. (This may include copying the environment strings into a +new array and assigning +.IR environ +to point to it.) +.P +In fact, for higher performance of +\fIgetenv\fR(), +implementations that do not provide +\fIputenv\fR() +could also maintain a separate copy of the environment in a data structure +that could be searched much more quickly (such as an indexed hash table, +or a binary tree), and update both it and the linear list at +.IR environ +when +\fIsetenv\fR() +or +\fIunsetenv\fR() +is invoked. On implementations that do provide +\fIputenv\fR(), +such a copy might still be worthwhile but would need to allow for the +fact that applications can directly modify the content of environment +strings added with +\fIputenv\fR(). +For example, if an environment string found by searching the copy is +one that was added using +\fIputenv\fR(), +the implementation would need to check that the string in +.IR environ +still has the same name (and value, if the copy includes values), and +whenever searching the copy produces no match the implementation would +then need to search each environment string in +.IR environ +that was added using +\fIputenv\fR() +in case any of them have changed their names and now match. Thus, each +use of +\fIputenv\fR() +to add to the environment would reduce the speed advantage of having +the copy. +.P +Performance of +\fIgetenv\fR() +can be important for applications which have large numbers of +environment variables. Typically, applications like this use the +environment as a resource database of user-configurable parameters. +The fact that these variables are in the user's shell environment +usually means that any other program that uses environment variables +(such as +.IR ls , +which attempts to use +.IR COLUMNS ), +or really almost any utility (\c +.IR LANG , +.IR LC_ALL , +and so on) is similarly slowed down by the linear search through the +variables. +.P +An implementation that maintains separate data structures, or even one +that manages the memory it consumes, is not currently required as it +was thought it would reduce consensus among implementors who do not +want to change their historical implementations. +.SH "FUTURE DIRECTIONS" +A future version may add one or more functions to access and modify the +environment in a thread-safe manner. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)", +.IR "\fIunsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/geteuid.3p b/upstream/archlinux/man3p/geteuid.3p new file mode 100644 index 00000000..2a6d8510 --- /dev/null +++ b/upstream/archlinux/man3p/geteuid.3p @@ -0,0 +1,86 @@ +'\" et +.TH GETEUID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +geteuid +\(em get the effective user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +uid_t geteuid(void); +.fi +.SH DESCRIPTION +The +\fIgeteuid\fR() +function shall return the effective user ID of the calling process. +The +\fIgeteuid\fR() +function shall not modify +.IR errno . +.SH "RETURN VALUE" +The +\fIgeteuid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +In a conforming environment, +\fIgeteuid\fR() +will always succeed. It is possible for implementations to provide +an extension where a process in a non-conforming environment will +not be associated with a user or group ID. It is recommended that such +implementations return (\c +.BR uid_t )\-1 +and set +.IR errno +to indicate such an environment; doing so does not violate +this standard, since such an environment is already an extension. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getgid.3p b/upstream/archlinux/man3p/getgid.3p new file mode 100644 index 00000000..f17a3e4c --- /dev/null +++ b/upstream/archlinux/man3p/getgid.3p @@ -0,0 +1,86 @@ +'\" et +.TH GETGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getgid +\(em get the real group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +gid_t getgid(void); +.fi +.SH DESCRIPTION +The +\fIgetgid\fR() +function shall return the real group ID of the calling process. +The +\fIgetgid\fR() +function shall not modify +.IR errno . +.SH "RETURN VALUE" +The +\fIgetgid\fR() +function shall always be successful and no return value is reserved +to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +In a conforming environment, +\fIgetgid\fR() +will always succeed. It is possible for implementations to +provide an extension where a process in a non-conforming +environment will not be associated with a user or group ID. +It is recommended that such implementations return (\c +.BR gid_t )\-1 +and set +.IR errno +to indicate such an environment; doing so does not violate +this standard, since such an environment is already an extension. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getgrent.3p b/upstream/archlinux/man3p/getgrent.3p new file mode 100644 index 00000000..73a26372 --- /dev/null +++ b/upstream/archlinux/man3p/getgrent.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETGRENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getgrent +\(em get the group database entry +.SH SYNOPSIS +.LP +.nf +#include +.P +struct group *getgrent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendgrent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getgrgid.3p b/upstream/archlinux/man3p/getgrgid.3p new file mode 100644 index 00000000..a2c6811f --- /dev/null +++ b/upstream/archlinux/man3p/getgrgid.3p @@ -0,0 +1,243 @@ +'\" et +.TH GETGRGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getgrgid, +getgrgid_r +\(em get group database entry for a group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +struct group *getgrgid(gid_t \fIgid\fP); +int getgrgid_r(gid_t \fIgid\fP, struct group *\fIgrp\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct group **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetgrgid\fR() +function shall search the group database for an entry with a matching +.IR gid . +.P +The +\fIgetgrgid\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrgid\fR(). +If +\fIgetgrgid\fR() +returns a null pointer and +.IR errno +is set to non-zero, an error occurred. +.P +The +\fIgetgrgid_r\fR() +function shall update the +.BR group +structure pointed to by +.IR grp +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the group database with a +matching +.IR gid . +Storage referenced by the group structure is allocated from the memory +provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +returns either \-1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetgrgid\fR() +shall return a pointer to a +.BR "struct group" +with the structure defined in +.IR +with a matching entry if one is found. The +\fIgetgrgid\fR() +function shall return a null pointer if either the requested entry was +not found, or an error occurred. If the requested entry was not found, +.IR errno +shall not be changed. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetgrent\fR(), +\fIgetgrgid\fR(), +or +\fIgetgrnam\fR(). +The returned pointer, and pointers within the structure, might +also be invalidated if the calling thread is terminated. +.P +If successful, the +\fIgetgrgid_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIgetgrgid\fR() +and +\fIgetgrgid_r\fR() +functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetgrgid\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIgetgrgid_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR group +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +may return \-1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetgrid_r\fR(). +.sp +.RS 4 +.nf + +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= -1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct group result; +struct group *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getgrgid_r(42, &result, buffer, len, &resultp)) =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi +.P +.RE +.SS "Finding an Entry in the Group Database" +.P +The following example uses +\fIgetgrgid\fR() +to search the group database for a group ID that was previously stored +in a +.BR stat +structure, then prints out the group name if it is found. If the group +is not found, the program prints the numeric value of the group for the +entry. +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +struct stat statbuf; +struct group *grp; +\&... +if ((grp = getgrgid(statbuf.st_gid)) != NULL) + printf(" %-8.8s", grp->gr_name); +else + printf(" %-8d", statbuf.st_gid); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetgrgid_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \-1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetgrnam\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getgrnam.3p b/upstream/archlinux/man3p/getgrnam.3p new file mode 100644 index 00000000..7d191f97 --- /dev/null +++ b/upstream/archlinux/man3p/getgrnam.3p @@ -0,0 +1,219 @@ +'\" et +.TH GETGRNAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getgrnam, +getgrnam_r +\(em search group database for a name +.SH SYNOPSIS +.LP +.nf +#include +.P +struct group *getgrnam(const char *\fIname\fP); +int getgrnam_r(const char *\fIname\fP, struct group *\fIgrp\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct group **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetgrnam\fR() +function shall search the group database for an entry with a matching +.IR name . +.P +The +\fIgetgrnam\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetgrnam\fR(). +If +\fIgetgrnam\fR() +returns a null pointer and +.IR errno +is set to non-zero, an error occurred. +.P +The +\fIgetgrnam_r\fR() +function shall update the +.BR group +structure pointed to by +.IR grp +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the group database with a +matching +.IR name . +Storage referenced by the +.BR group +structure is allocated from the memory provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +returns either \-1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer is returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetgrnam\fR() +function shall return a pointer to a +.BR "struct group" +with the structure defined in +.IR +with a matching entry if one is found. The +\fIgetgrnam\fR() +function shall return a null pointer if either the requested entry +was not found, or an error occurred. If the requested entry was +not found, +.IR errno +shall not be changed. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetgrent\fR(), +\fIgetgrgid\fR(), +or +\fIgetgrnam\fR(). +The returned pointer, and pointers within the structure, might +also be invalidated if the calling thread is terminated. +.P +The +\fIgetgrnam_r\fR() +function shall return zero on success or if the requested entry was not +found and no error has occurred. If any error has occurred, an error +number shall be returned to indicate the error. +.SH ERRORS +The +\fIgetgrnam\fR() +and +\fIgetgrnam_r\fR() +functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetgrnam\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the +system. +.P +The +\fIgetgrnam_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR group +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETGR_R_SIZE_MAX) +may return \-1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetgrnam_r\fR(). +.sp +.RS 4 +.nf + +long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX); +size_t len; +if (initlen =\|= -1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct group result; +struct group *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getgrnam_r("somegroup", &result, buffer, len, &resultp)) + =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetgrnam_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \-1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETGR_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendgrent\fR\^(\|)", +.IR "\fIgetgrgid\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getgroups.3p b/upstream/archlinux/man3p/getgroups.3p new file mode 100644 index 00000000..0db60db0 --- /dev/null +++ b/upstream/archlinux/man3p/getgroups.3p @@ -0,0 +1,147 @@ +'\" et +.TH GETGROUPS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getgroups +\(em get supplementary group IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int getgroups(int \fIgidsetsize\fP, gid_t \fIgrouplist\fP[]); +.fi +.SH DESCRIPTION +The +\fIgetgroups\fR() +function shall fill in the array +.IR grouplist +with the current supplementary group IDs of the calling process. It is +implementation-defined whether +\fIgetgroups\fR() +also returns the effective group ID in the +.IR grouplist +array. +.P +The +.IR gidsetsize +argument specifies the number of elements in the array +.IR grouplist . +The actual number of group IDs stored in the array shall be returned. +The values of array entries with indices greater than or equal to the +value returned are undefined. +.P +If +.IR gidsetsize +is 0, +\fIgetgroups\fR() +shall return the number of group IDs that it would otherwise return +without modifying the array pointed to by +.IR grouplist . +.P +If the effective group ID of the process is returned with the +supplementary group IDs, the value returned shall always be greater +than or equal to one and less than or equal to the value of +{NGROUPS_MAX}+1. +.SH "RETURN VALUE" +Upon successful completion, the number of supplementary group IDs shall +be returned. A return value of \-1 indicates failure and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIgetgroups\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR gidsetsize +argument is non-zero and less than the number of group IDs that would +have been returned. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Supplementary Group IDs of the Calling Process" +.P +The following example places the current supplementary group IDs of the +calling process into the +.IR group +array. +.sp +.RS 4 +.nf + +#include +#include +\&... +gid_t *group; +int nogroups; +long ngroups_max; +.P +ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1; +group = (gid_t *)malloc(ngroups_max *sizeof(gid_t)); +.P +ngroups = getgroups(ngroups_max, group); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The related function +\fIsetgroups\fR() +is a privileged operation and therefore is not covered by this volume of POSIX.1\(hy2017. +.P +As implied by the definition of supplementary groups, the effective +group ID +may appear in the array returned by +\fIgetgroups\fR() +or it may be returned only by +\fIgetegid\fR(). +Duplication may exist, but the application needs to call +\fIgetegid\fR() +to be sure of getting all of the information. Various implementation +variations and administrative sequences cause the set of groups +appearing in the result of +\fIgetgroups\fR() +to vary in order and as to whether the effective group ID is included, +even when the set of groups is the same (in the mathematical sense of +``set''). (The history of a process and its parents could affect the +details of the result.) +.P +Application developers should note that +{NGROUPS_MAX} +is not necessarily a constant on all implementations. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/gethostent.3p b/upstream/archlinux/man3p/gethostent.3p new file mode 100644 index 00000000..0777f70a --- /dev/null +++ b/upstream/archlinux/man3p/gethostent.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETHOSTENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +gethostent +\(em network host database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct hostent *gethostent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendhostent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/gethostid.3p b/upstream/archlinux/man3p/gethostid.3p new file mode 100644 index 00000000..63cb246a --- /dev/null +++ b/upstream/archlinux/man3p/gethostid.3p @@ -0,0 +1,62 @@ +'\" et +.TH GETHOSTID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +gethostid +\(em get an identifier for the current host +.SH SYNOPSIS +.LP +.nf +#include +.P +long gethostid(void); +.fi +.SH DESCRIPTION +The +\fIgethostid\fR() +function shall retrieve a 32-bit identifier for the current host. +.SH "RETURN VALUE" +Upon successful completion, +\fIgethostid\fR() +shall return an identifier for the current host. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This volume of POSIX.1\(hy2017 does not define the domain in which the return value is unique. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIinitstate\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/gethostname.3p b/upstream/archlinux/man3p/gethostname.3p new file mode 100644 index 00000000..7f6c678c --- /dev/null +++ b/upstream/archlinux/man3p/gethostname.3p @@ -0,0 +1,75 @@ +'\" et +.TH GETHOSTNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +gethostname +\(em get name of current host +.SH SYNOPSIS +.LP +.nf +#include +.P +int gethostname(char *\fIname\fP, size_t \fInamelen\fP); +.fi +.SH DESCRIPTION +The +\fIgethostname\fR() +function shall return the standard host name for the current machine. +The +.IR namelen +argument shall specify the size of the array pointed to by the +.IR name +argument. The returned name shall be null-terminated, except that if +.IR namelen +is an insufficient length to hold the host name, then the returned name +shall be truncated and it is unspecified whether the returned name is +null-terminated. +.P +Host names are limited to +{HOST_NAME_MAX} +bytes. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \-1 shall +be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgethostid\fR\^(\|)", +.IR "\fIuname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getitimer.3p b/upstream/archlinux/man3p/getitimer.3p new file mode 100644 index 00000000..522282a3 --- /dev/null +++ b/upstream/archlinux/man3p/getitimer.3p @@ -0,0 +1,169 @@ +'\" et +.TH GETITIMER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getitimer, +setitimer +\(em get and set value of interval timer +.SH SYNOPSIS +.LP +.nf +#include +.P +int getitimer(int \fIwhich\fP, struct itimerval *\fIvalue\fP); +int setitimer(int \fIwhich\fP, const struct itimerval *restrict \fIvalue\fP, + struct itimerval *restrict \fIovalue\fP); +.fi +.SH DESCRIPTION +The +\fIgetitimer\fR() +function shall store the current value of the timer specified by +.IR which +into the structure pointed to by +.IR value . +The +\fIsetitimer\fR() +function shall set the timer specified by +.IR which +to the value specified in the structure pointed to by +.IR value , +and if +.IR ovalue +is not a null pointer, store the previous value of the timer in the +structure pointed to by +.IR ovalue . +.P +A timer value is defined by the +.BR itimerval +structure, specified in +.IR . +If +.IR it_value +is non-zero, it shall indicate the time to the next timer expiration. +If +.IR it_interval +is non-zero, it shall specify a value to be used in reloading +.IR it_value +when the timer expires. Setting +.IR it_value +to 0 shall disable a timer, regardless of the value of +.IR it_interval . +Setting +.IR it_interval +to 0 shall disable a timer after its next expiration (assuming +.IR it_value +is non-zero). +.P +Implementations may place limitations on the granularity of timer +values. For each interval timer, if the requested timer value requires +a finer granularity than the implementation supports, the actual timer +value shall be rounded up to the next supported value. +.P +An XSI-conforming implementation provides each process with at least +three interval timers, which are indicated by the +.IR which +argument: +.IP ITIMER_PROF 14 +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 ITIMER_PROF timer expires, the SIGPROF signal is delivered. +.IP ITIMER_REAL 14 +Decrements in real time. A SIGALRM signal is delivered when this timer +expires. +.IP ITIMER_VIRTUAL 14 +Decrements in process virtual time. It runs only when the process is +executing. A SIGVTALRM signal is delivered when it expires. +.P +The interaction between +\fIsetitimer\fR() +and +\fIalarm\fR() +or +\fIsleep\fR() +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetitimer\fR() +or +\fIsetitimer\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetitimer\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR value +argument is not in canonical form. (In canonical form, the number of +microseconds is a non-negative integer less than 1\|000\|000 and the +number of seconds is a non-negative integer.) +.P +The +\fIgetitimer\fR() +and +\fIsetitimer\fR() +functions may fail if: +.TP +.BR EINVAL +The +.IR which +argument is not recognized. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fItimer_gettime\fR() +and +\fItimer_settime\fR() +functions instead of the obsolescent +\fIgetitimer\fR() +and +\fIsetitimer\fR() +functions, respectively. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIgetitimer\fR() +and +\fIsetitimer\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIsleep\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getline.3p b/upstream/archlinux/man3p/getline.3p new file mode 100644 index 00000000..84ec7ea7 --- /dev/null +++ b/upstream/archlinux/man3p/getline.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETLINE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getline +\(em read a delimited record from +.IR stream +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t getline(char **restrict \fIlineptr\fP, size_t *restrict \fIn\fP, + FILE *restrict \fIstream\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetdelim\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getlogin.3p b/upstream/archlinux/man3p/getlogin.3p new file mode 100644 index 00000000..5e766171 --- /dev/null +++ b/upstream/archlinux/man3p/getlogin.3p @@ -0,0 +1,229 @@ +'\" et +.TH GETLOGIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getlogin, +getlogin_r +\(em get login name +.SH SYNOPSIS +.LP +.nf +#include +.P +char *getlogin(void); +int getlogin_r(char *\fIname\fP, size_t \fInamesize\fP); +.fi +.SH DESCRIPTION +The +\fIgetlogin\fR() +function shall return a pointer to a string containing the user name +associated by the login activity with the controlling terminal of the +current process. If +\fIgetlogin\fR() +returns a non-null pointer, then that pointer points to the name that +the user logged in under, even if there are several login names with +the same user ID. +.P +The +\fIgetlogin\fR() +function need not be thread-safe. +.P +The +\fIgetlogin_r\fR() +function shall put the name associated by the login activity with the +controlling terminal of the current process in the character array +pointed to by +.IR name . +The array is +.IR namesize +characters long and should have space for the name and the terminating +null character. The maximum size of the login name is +{LOGIN_NAME_MAX}. +.P +If +\fIgetlogin_r\fR() +is successful, +.IR name +points to the name the user used at login, even if there are several +login names with the same user ID. +.P +The +\fIgetlogin\fR() +and +\fIgetlogin_r\fR() +functions may make use of file descriptors 0, 1, and 2 to find the +controlling terminal of the current process, examining each in turn +until the terminal is found. If in this case none of these three file +descriptors is open to the controlling terminal, these functions may +fail. The method used to find the terminal associated with a file +descriptor may depend on the file descriptor being open to the actual +terminal device, not +.BR /dev/tty . +.SH "RETURN VALUE" +Upon successful completion, +\fIgetlogin\fR() +shall return a pointer to the login name or a null pointer if the +user's login name cannot be found. Otherwise, it shall return a null +pointer and set +.IR errno +to indicate the error. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIgetlogin\fR(). +The returned pointer and the string content might also be invalidated +if the calling thread is terminated. +.P +If successful, the +\fIgetlogin_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOTTY +None of the file descriptors 0, 1, or 2 is open to the controlling +terminal of the current process. +.TP +.BR ENXIO +The calling process has no controlling terminal. +.P +The +\fIgetlogin_r\fR() +function may fail if: +.TP +.BR ERANGE +The value of +.IR namesize +is smaller than the length of the string to be returned including the +terminating null character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the User Login Name" S +.P +The following example calls the +\fIgetlogin\fR() +function to obtain the name of the user associated with the calling +process, and passes this information to the +\fIgetpwnam\fR() +function to get the associated user database information. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\en"); exit(1); + } +.fi +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +shall return the name associated with the effective user ID of the +process; +\fIgetlogin\fR() +shall return the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +shall return the name associated with the real user ID of the process. +.P +The +\fIgetlogin_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.SH RATIONALE +The +\fIgetlogin\fR() +function returns a pointer to the user's login name. The same user ID +may be shared by several login names. If it is desired to get the user +database entry that is used during login, the result of +\fIgetlogin\fR() +should be used to provide the argument to the +\fIgetpwnam\fR() +function. (This might be used to determine the user's login shell, +particularly where a single user has multiple login shells with +distinct login names, but the same user ID.) +.P +The information provided by the +.IR cuserid (\|) +function, which was originally defined in the POSIX.1\(hy1988 standard and subsequently +removed, can be obtained by the following: +.sp +.RS 4 +.nf + +getpwuid(geteuid()) +.fi +.P +.RE +.P +while the information provided by historical implementations of +.IR cuserid (\|) +can be obtained by: +.sp +.RS 4 +.nf + +getpwuid(getuid()) +.fi +.P +.RE +.P +The thread-safe version of this function places the user name in a +user-supplied buffer and returns a non-zero value if it fails. The +non-thread-safe version may return the name in a static data area that +may be overwritten by each call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgetpwuid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getmsg.3p b/upstream/archlinux/man3p/getmsg.3p new file mode 100644 index 00000000..aff2b244 --- /dev/null +++ b/upstream/archlinux/man3p/getmsg.3p @@ -0,0 +1,412 @@ +'\" et +.TH GETMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getmsg, +getpmsg +\(em receive next message from a STREAMS file (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int getmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP, + struct strbuf *restrict \fIdataptr\fP, int *restrict \fIflagsp\fP); +int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP, + struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP, + int *restrict \fIflagsp\fP); +.fi +.SH DESCRIPTION +The +\fIgetmsg\fR() +function shall retrieve the contents of a message located at the head +of the STREAM head read queue associated with a STREAMS file and place +the contents into one or more buffers. The message contains either a +data part, a control part, or both. The data and control parts of the +message shall be placed into separate buffers, as described below. The +semantics of each part are defined by the originator of the message. +.P +The +\fIgetpmsg\fR() +function shall be equivalent to +\fIgetmsg\fR(), +except that it provides finer control over the priority of the messages +received. Except where noted, all requirements on +\fIgetmsg\fR() +also pertain to +\fIgetpmsg\fR(). +.P +The +.IR fildes +argument specifies a file descriptor referencing a STREAMS-based file. +.P +The +.IR ctlptr +and +.IR dataptr +arguments each point to a +.BR strbuf +structure, in which the +.IR buf +member points to a buffer in which the data or control information is +to be placed, and the +.IR maxlen +member indicates the maximum number of bytes this buffer can hold. On +return, the +.IR len +member shall contain the number of bytes of data or control information +actually received. The +.IR len +member shall be set to 0 if there is a zero-length control or data part +and +.IR len +shall be set to \-1 if no data or control information is present in +the message. +.P +When +\fIgetmsg\fR() +is called, +.IR flagsp +should point to an integer that indicates the type of message the +process is able to receive. This is described further below. +.P +The +.IR ctlptr +argument is used to hold the control part of the message, and +.IR dataptr +is used to hold the data part of the message. If +.IR ctlptr +(or +.IR dataptr ) +is a null pointer or the +.IR maxlen +member is \-1, the control (or data) part of the message shall not be +processed and shall be left on the STREAM head read queue, and if the +.IR ctlptr +(or +.IR dataptr ) +is not a null pointer, +.IR len +shall be set to \-1. If the +.IR maxlen +member is set to 0 and there is a zero-length control (or data) part, +that zero-length part shall be removed from the read queue and +.IR len +shall be set to 0. If the +.IR maxlen +member is set to 0 and there are more than 0 bytes of control (or data) +information, that information shall be left on the read queue and +.IR len +shall be set to 0. If the +.IR maxlen +member in +.IR ctlptr +(or +.IR dataptr ) +is less than the control (or data) part of the message, +.IR maxlen +bytes shall be retrieved. In this case, the remainder of the message +shall be left on the STREAM head read queue and a non-zero return value +shall be provided. +.P +By default, +\fIgetmsg\fR() +shall process the first available message on the STREAM head read +queue. However, a process may choose to retrieve only high-priority +messages by setting the integer pointed to by +.IR flagsp +to RS_HIPRI. In this case, +\fIgetmsg\fR() +shall only process the next message if it is a high-priority message. +When the integer pointed to by +.IR flagsp +is 0, any available message shall be retrieved. In this case, on +return, the integer pointed to by +.IR flagsp +shall be set to RS_HIPRI if a high-priority message was retrieved, or 0 +otherwise. +.P +For +\fIgetpmsg\fR(), +the flags are different. The +.IR flagsp +argument points to a bitmask with the following mutually-exclusive +flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. +Like +\fIgetmsg\fR(), +\fIgetpmsg\fR() +shall process the first available message on the STREAM head read +queue. A process may choose to retrieve only high-priority messages by +setting the integer pointed to by +.IR flagsp +to MSG_HIPRI and the integer pointed to by +.IR bandp +to 0. In this case, +\fIgetpmsg\fR() +shall only process the next message if it is a high-priority message. +In a similar manner, a process may choose to retrieve a message from a +particular priority band by setting the integer pointed to by +.IR flagsp +to MSG_BAND and the integer pointed to by +.IR bandp +to the priority band of interest. In this case, +\fIgetpmsg\fR() +shall only process the next message if it is in a priority band equal +to, or greater than, the integer pointed to by +.IR bandp , +or if it is a high-priority message. If a process wants to get the +first message off the queue, the integer pointed to by +.IR flagsp +should be set to MSG_ANY and the integer pointed to by +.IR bandp +should be set to 0. On return, if the message retrieved was a +high-priority message, the integer pointed to by +.IR flagsp +shall be set to MSG_HIPRI and the integer pointed to by +.IR bandp +shall be set to 0. Otherwise, the integer pointed to by +.IR flagsp +shall be set to MSG_BAND and the integer pointed to by +.IR bandp +shall be set to the priority band of the message. +.P +If O_NONBLOCK is not set, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall block until a message of the type specified by +.IR flagsp +is available at the front of the STREAM head read queue. If O_NONBLOCK +is set and a message of the specified type is not present at the front +of the read queue, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] . +.P +If a hangup occurs on the STREAM from which messages are retrieved, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall continue to operate normally, as described above, until the +STREAM head read queue is empty. Thereafter, they shall return 0 in the +.IR len +members of +.IR ctlptr +and +.IR dataptr . +.SH "RETURN VALUE" +Upon successful completion, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall return a non-negative value. A value of 0 indicates that a full +message was read successfully. A return value of MORECTL indicates +that more control +information is waiting for retrieval. A return value of MOREDATA +indicates that more data is waiting for retrieval. A return value of +the bitwise-logical OR of MORECTL and MOREDATA indicates that both +types of information remain. Subsequent +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +calls shall retrieve the remainder of the message. However, if a message +of higher priority has come in on the STREAM head read queue, the next +call to +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +shall retrieve that higher-priority message before retrieving the +remainder of the previous message. +.P +If the high priority control part of the message is consumed, the +message shall be placed back on the queue as a normal message of band +0. Subsequent +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +calls shall retrieve the remainder of the message. If, however, a +priority message arrives or already exists on the STREAM head, the +subsequent call to +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +shall retrieve the higher-priority message before retrieving the +remainder of the message that was put back. +.P +Upon failure, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +functions shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set and no messages are available. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor open for reading. +.TP +.BR EBADMSG +The queued message to be read is not valid for +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +or a pending file descriptor is at the STREAM head. +.TP +.BR EINTR +A signal was caught during +\fIgetmsg\fR() +or +\fIgetpmsg\fR(). +.TP +.BR EINVAL +An illegal value was specified by +.IR flagsp , +or the STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.TP +.BR ENOSTR +A STREAM is not associated with +.IR fildes . +.P +In addition, +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +shall fail if the STREAM head had processed an asynchronous error +before the call. In this case, the value of +.IR errno +does not reflect the result of +\fIgetmsg\fR() +or +\fIgetpmsg\fR() +but reflects the prior error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting Any Message" +.P +In the following example, the value of +.IR fd +is assumed to refer to an open STREAMS file. The call to +\fIgetmsg\fR() +retrieves any available message on the associated STREAM-head read +queue, returning control and data information to the buffers pointed to +by +.IR ctrlbuf +and +.IR databuf , +respectively. +.sp +.RS 4 +.nf + +#include +\&... +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int flags = 0; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.P +data.buf = databuf; +data.maxlen = sizeof(databuf); +.P +ret = getmsg (fd, &ctrl, &data, &flags); +.fi +.P +.RE +.SS "Getting the First Message off the Queue" +.P +In the following example, the call to +\fIgetpmsg\fR() +retrieves the first available message on the associated STREAM-head +read queue. +.sp +.RS 4 +.nf + +#include +\&... +.P +int fd; +char ctrlbuf[128]; +char databuf[512]; +struct strbuf ctrl; +struct strbuf data; +int band = 0; +int flags = MSG_ANY; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.maxlen = sizeof(ctrlbuf); +.P +data.buf = databuf; +data.maxlen = sizeof(databuf); +.P +ret = getpmsg (fd, &ctrl, &data, &band, &flags); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIgetmsg\fR() +and +\fIgetpmsg\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getnameinfo.3p b/upstream/archlinux/man3p/getnameinfo.3p new file mode 100644 index 00000000..3415d4ae --- /dev/null +++ b/upstream/archlinux/man3p/getnameinfo.3p @@ -0,0 +1,236 @@ +'\" et +.TH GETNAMEINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getnameinfo +\(em get name information +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int getnameinfo(const struct sockaddr *restrict \fIsa\fP, socklen_t \fIsalen\fP, + char *restrict \fInode\fP, socklen_t \fInodelen\fP, char *restrict \fIservice\fP, + socklen_t \fIservicelen\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIgetnameinfo\fR() +function shall translate a socket address to a node name and service +location, all of which are defined as in +.IR "\fIfreeaddrinfo\fR\^(\|)". +.P +The +.IR sa +argument points to a socket address structure to be translated. The +.IR salen +argument contains the length of the address pointed to by +.IR sa . +.P +If the socket address structure contains an IPv4-mapped IPv6 address or +an IPv4-compatible IPv6 address, the implementation shall extract the +embedded IPv4 address and lookup the node name for that IPv4 address. +.P +If the address is the IPv6 unspecified address (\c +.BR \(dq::\(dq ), +a lookup shall not be performed and the behavior shall be the same as +when the node's name cannot be located. +.P +If the +.IR node +argument is non-NULL and the +.IR nodelen +argument is non-zero, then the +.IR node +argument points to a buffer able to contain up to +.IR nodelen +bytes that receives the node name as a null-terminated string. If the +.IR node +argument is NULL or the +.IR nodelen +argument is zero, the node name shall not be returned. If the node's +name cannot be located, the numeric form of the address contained +in the socket address structure pointed to by the +.IR sa +argument is returned instead of its name. +.P +If the +.IR service +argument is non-NULL and the +.IR servicelen +argument is non-zero, then the +.IR service +argument points to a buffer able to contain up to +.IR servicelen +bytes that receives the service name as a null-terminated string. +If the +.IR service +argument is NULL or the +.IR servicelen +argument is zero, the service name shall not be returned. If the +service's name cannot be located, the numeric form of the service +address (for example, its port number) shall be returned instead of +its name. +.P +The +.IR flags +argument is a flag that changes the default actions of the function. By +default the fully-qualified domain name (FQDN) for the +host shall be returned, but: +.IP " *" 4 +If the flag bit NI_NOFQDN is set, only the node name portion of the +FQDN shall be returned for local hosts. +.IP " *" 4 +If the flag bit NI_NUMERICHOST is set, the numeric form of the address +contained in the socket address structure pointed to by the +.IR sa +argument shall be returned instead of its name. +.IP " *" 4 +If the flag bit NI_NAMEREQD is set, an error shall be returned if the +host's name cannot be located. +.IP " *" 4 +If the flag bit NI_NUMERICSERV is set, the numeric form of the service +address shall be returned (for example, its port number) instead of its +name. +.IP " *" 4 +If the flag bit NI_NUMERICSCOPE is set, the numeric form of the scope +identifier shall be returned (for example, interface index) instead of +its name. This flag shall be ignored if the +.IR sa +argument is not an IPv6 address. +.IP " *" 4 +If the flag bit NI_DGRAM is set, this indicates that the service is a +datagram service (SOCK_DGRAM). The default behavior shall assume that +the service is a stream service (SOCK_STREAM). +.TP 10 +.BR Notes: +.RS 10 +.IP " 1." 4 +The two NI_NUMERICxxx flags are required to support the +.BR \-n +flag that many commands provide. +.IP " 2." 4 +The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port +numbers (for example, [512,514]) that represent different services for +UDP and TCP. +.RE +.P +.P +The +\fIgetnameinfo\fR() +function shall be thread-safe. +.SH "RETURN VALUE" +A zero return value for +\fIgetnameinfo\fR() +indicates successful completion; a non-zero return value indicates +failure. The possible values for the failures are listed in the +ERRORS section. +.P +Upon successful completion, +\fIgetnameinfo\fR() +shall return the +.IR node +and +.IR service +names, if requested, in the buffers provided. The returned names are +always null-terminated strings. +.SH ERRORS +The +\fIgetnameinfo\fR() +function shall fail and return the corresponding value if: +.IP [EAI_AGAIN] 12 +The name could not be resolved at this time. Future attempts may +succeed. +.IP [EAI_BADFLAGS] 12 +.br +The +.IR flags +had an invalid value. +.IP [EAI_FAIL] 12 +A non-recoverable error occurred. +.IP [EAI_FAMILY] 12 +The address family was not recognized or the address length was invalid +for the specified family. +.IP [EAI_MEMORY] 12 +There was a memory allocation failure. +.IP [EAI_NONAME] 12 +The name does not resolve for the supplied parameters. +.RS 12 +.P +NI_NAMEREQD is set and the host's name cannot be located, or both +.IR nodename +and +.IR servname +were null. +.RE +.IP [EAI_OVERFLOW] 12 +.br +An argument buffer overflowed. The buffer pointed to by the +.IR node +argument or the +.IR service +argument was too small. +.IP [EAI_SYSTEM] 12 +A system error occurred. The error code can be found in +.IR errno . +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +If the returned values are to be used as part of any further name +resolution (for example, passed to +\fIgetaddrinfo\fR()), +applications should provide buffers large enough to store any result +possible on the system. +.P +Given the IPv4-mapped IPv6 address +.BR \(dq::ffff:1.2.3.4\(dq , +the implementation performs a lookup as if the socket address structure +contains the IPv4 address +.BR \(dq1.2.3.4\(dq . +.P +The IPv6 unspecified address (\c +.BR \(dq::\(dq ) +and the IPv6 loopback address (\c +.BR \(dq::1\(dq ) +are not IPv4-compatible addresses. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendservent\fR\^(\|)", +.IR "\fIfreeaddrinfo\fR\^(\|)", +.IR "\fIgai_strerror\fR\^(\|)", +.IR "\fIinet_ntop\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getnetbyaddr.3p b/upstream/archlinux/man3p/getnetbyaddr.3p new file mode 100644 index 00000000..d460d00d --- /dev/null +++ b/upstream/archlinux/man3p/getnetbyaddr.3p @@ -0,0 +1,44 @@ +'\" et +.TH GETNETBYADDR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getnetbyaddr, +getnetbyname, +getnetent +\(em network database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct netent *getnetbyaddr(uint32_t \fInet\fP, int \fItype\fP); +struct netent *getnetbyname(const char *\fIname\fP); +struct netent *getnetent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendnetent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getopt.3p b/upstream/archlinux/man3p/getopt.3p new file mode 100644 index 00000000..4ec10bb2 --- /dev/null +++ b/upstream/archlinux/man3p/getopt.3p @@ -0,0 +1,462 @@ +'\" et +.TH GETOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getopt, +optarg, +opterr, +optind, +optopt +\(em command option parsing +.SH SYNOPSIS +.LP +.nf +#include +.P +int getopt(int \fIargc\fP, char * const \fIargv\fP[], const char *\fIoptstring\fP); +extern char *optarg; +extern int opterr, optind, optopt; +.fi +.SH DESCRIPTION +The +\fIgetopt\fR() +function is a command-line parser that shall follow Utility Syntax +Guidelines 3, 4, 5, 6, 7, 9, and 10 in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The parameters +.IR argc +and +.IR argv +are the argument count and argument array as passed to +\fImain\fR() +(see +\fIexec\fR()). +The argument +.IR optstring +is a string of recognized option characters; if a character is followed +by a +, +the option takes an argument. All option characters allowed by Utility +Syntax Guideline 3 are allowed in +.IR optstring . +The implementation may accept other characters as an extension. +.P +The variable +.IR optind +is the index of the next element of the +.IR argv [\^] +vector to be processed. It shall be initialized to 1 by the system, and +\fIgetopt\fR() +shall update it when it finishes with each element of +.IR argv [\|]. +If the application sets +.IR optind +to zero before calling +\fIgetopt\fR(), +the behavior is unspecified. When an element of +.IR argv [\|] +contains multiple option characters, it is unspecified how +\fIgetopt\fR() +determines which options have already been processed. +.P +The +\fIgetopt\fR() +function shall return the next option character (if one is found) from +.IR argv +that matches a character in +.IR optstring , +if there is one that matches. If the option takes an argument, +\fIgetopt\fR() +shall set the variable +.IR optarg +to point to the option-argument as follows: +.IP " 1." 4 +If the option was the last character in the string pointed to by an +element of +.IR argv , +then +.IR optarg +shall contain the next element of +.IR argv , +and +.IR optind +shall be incremented by 2. If the resulting value of +.IR optind +is greater than +.IR argc , +this indicates a missing option-argument, and +\fIgetopt\fR() +shall return an error indication. +.IP " 2." 4 +Otherwise, +.IR optarg +shall point to the string following the option character in that +element of +.IR argv , +and +.IR optind +shall be incremented by 1. +.P +If, when +\fIgetopt\fR() +is called: +.sp +.RS 4 +.nf + + \fIargv\fP[optind] \fRis a null pointer\fP +*\fIargv\fP[optind] \fRis not the character\fP \- + \fIargv\fP[optind] \fRpoints to the string\fP "\-" +.fi +.P +.RE +.P +\fIgetopt\fR() +shall return \-1 without changing +.IR optind . +If: +.sp +.RS 4 +.nf + +\fIargv\fP[optind] \fRpoints to the string\fP "\-\|\-" +.fi +.P +.RE +.P +\fIgetopt\fR() +shall return \-1 after incrementing +.IR optind . +.P +If +\fIgetopt\fR() +encounters an option character that is not contained in +.IR optstring , +it shall return the + +(\c +.BR '?' ) +character. If it detects a missing option-argument, it shall return the + +character (\c +.BR ':' ) +if the first character of +.IR optstring +was a +, +or a + +character (\c +.BR '?' ) +otherwise. In either case, +\fIgetopt\fR() +shall set the variable +.IR optopt +to the option character that caused the error. If the application has +not set the variable +.IR opterr +to 0 and the first character of +.IR optstring +is not a +, +\fIgetopt\fR() +shall also print a diagnostic message to +.IR stderr +in the format specified for the +.IR getopts +utility, unless the +.IR stderr +stream has wide orientation, in which case the behavior is undefined. +.P +The +\fIgetopt\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIgetopt\fR() +function shall return the next option character specified on the command +line. +.P +A + +(\c +.BR ':' ) +shall be returned if +\fIgetopt\fR() +detects a missing argument and the first character of +.IR optstring +was a + +(\c +.BR ':' ). +.P +A + +(\c +.BR '?' ) +shall be returned if +\fIgetopt\fR() +encounters an option character not in +.IR optstring +or detects a missing argument and the first character of +.IR optstring +was not a + +(\c +.BR ':' ). +.P +Otherwise, +\fIgetopt\fR() +shall return \-1 when all command line options are parsed. +.SH ERRORS +If the application has not set the variable +.IR opterr +to 0, the first character of +.IR optstring +is not a +, +and a write error occurs while +\fIgetopt\fR() +is printing a diagnostic message to +.IR stderr , +then the error indicator for +.IR stderr +shall be set; but +\fIgetopt\fR() +shall still succeed and the value of +.IR errno +after +\fIgetopt\fR() +is unspecified. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Parsing Command Line Options" +.P +The following code fragment shows how you might process the arguments +for a utility that can take the mutually-exclusive options +.IR a +and +.IR b +and the options +.IR f +and +.IR o , +both of which require arguments: +.sp +.RS 4 +.nf + +#include +#include +#include +.P +int +main(int argc, char *argv[ ]) +{ + int c; + int bflg = 0, aflg = 0, errflg = 0; + char *ifile; + char *ofile; + . . . + while ((c = getopt(argc, argv, ":abf:o:")) != -1) { + switch(c) { + case \(aqa\(aq: + if (bflg) + errflg++; + else + aflg++; + break; + case \(aqb\(aq: + if (aflg) + errflg++; + else + bflg++; + break; + case \(aqf\(aq: + ifile = optarg; + break; + case \(aqo\(aq: + ofile = optarg; + break; + case \(aq:\(aq: /* -f or -o without operand */ + fprintf(stderr, + "Option -%c requires an operand\en", optopt); + errflg++; + break; + case \(aq?\(aq: + fprintf(stderr, + "Unrecognized option: \(aq-%c\(aq\en", optopt); + errflg++; + } + } + if (errflg) { + fprintf(stderr, "usage: . . . "); + exit(2); + } + for ( ; optind < argc; optind++) { + if (access(argv[optind], R_OK)) { + . . . +} +.fi +.P +.RE +.P +This code accepts any of the following as equivalent: +.sp +.RS 4 +.nf + +cmd -ao arg path path +cmd -a -o arg path path +cmd -o arg -a path path +cmd -a -o arg -- path path +cmd -a -oarg path path +cmd -aoarg path path +.fi +.P +.RE +.SS "Selecting Options from the Command Line" +.P +The following example selects the type of database routines the user +wants to use based on the +.IR Options +argument. +.sp +.RS 4 +.nf + +#include +#include +\&... +const char *Options = "hdbtl"; +\&... +int dbtype, c; +char *st; +\&... +dbtype = 0; +while ((c = getopt(argc, argv, Options)) != -1) { + if ((st = strchr(Options, c)) != NULL) { + dbtype = st - Options; + break; + } +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetopt\fR() +function is only required to support option characters included in +Utility Syntax Guideline 3. Many historical implementations of +\fIgetopt\fR() +support other characters as options. This is an allowed extension, but +applications that use extensions are not maximally portable. Note that +support for multi-byte option characters is only possible when such +characters can be represented as type +.BR int . +.P +Applications which use wide-character output functions with +.IR stderr +should ensure that any calls to +\fIgetopt\fR() +do not write to +.IR stderr , +either by setting +.IR opterr +to 0 or by ensuring the first character of +.IR optstring +is always a +. +.P +While +.IR ferror ( stderr ) +may be used to detect failures to write a diagnostic to +.IR stderr +when +\fIgetopt\fR() +returns +.BR '?' , +the value of +.IR errno +is unspecified in such a condition. Applications desiring more control +over handling write failures should set +.IR opterr +to 0 and independently perform output to +.IR stderr , +rather than relying on +\fIgetopt\fR() +to do the output. +.SH RATIONALE +The +.IR optopt +variable represents historical practice and allows the application to +obtain the identity of the invalid option. +.P +The description has been written to make it clear that +\fIgetopt\fR(), +like the +.IR getopts +utility, deals with option-arguments whether separated from the option +by + +characters or not. Note that the requirements on +\fIgetopt\fR() +and +.IR getopts +are more stringent than the Utility Syntax Guidelines. +.P +The +\fIgetopt\fR() +function shall return \-1, rather than EOF, so that +.IR +is not required. +.P +The special significance of a + +as the first character of +.IR optstring +makes +\fIgetopt\fR() +consistent with the +.IR getopts +utility. It allows an application to make a distinction between a +missing argument and an incorrect option letter without having to +examine the option letter. It is true that a missing argument can only +be detected in one case, but that is a case that has to be considered. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIgetopts\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpeername.3p b/upstream/archlinux/man3p/getpeername.3p new file mode 100644 index 00000000..5e04872d --- /dev/null +++ b/upstream/archlinux/man3p/getpeername.3p @@ -0,0 +1,123 @@ +'\" et +.TH GETPEERNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpeername +\(em get the name of the peer socket +.SH SYNOPSIS +.LP +.nf +#include +.P +int getpeername(int \fIsocket\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIgetpeername\fR() +function shall retrieve the peer address of the specified socket, +store this address in the +.BR sockaddr +structure pointed to by the +.IR address +argument, and store the length of this address in the object pointed +to by the +.IR address_len +argument. +.P +The +.IR address_len +argument points to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the protocol permits connections by unbound clients, and the peer is +not bound, then the value stored in the object pointed to by +.IR address +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetpeername\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINVAL +The socket has been shut down. +.TP +.BR ENOTCONN +The socket is not connected or otherwise has not had the peer +pre-specified. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The operation is not supported for the socket protocol. +.P +The +\fIgetpeername\fR() +function may fail if: +.TP +.BR ENOBUFS +Insufficient resources were available in the system to complete the +call. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.br +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpgid.3p b/upstream/archlinux/man3p/getpgid.3p new file mode 100644 index 00000000..8d7df021 --- /dev/null +++ b/upstream/archlinux/man3p/getpgid.3p @@ -0,0 +1,100 @@ +'\" et +.TH GETPGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpgid +\(em get the process group ID for a process +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getpgid(pid_t \fIpid\fP); +.fi +.SH DESCRIPTION +The +\fIgetpgid\fR() +function shall return the process group ID of the process whose process +ID is equal to +.IR pid . +If +.IR pid +is equal to 0, +\fIgetpgid\fR() +shall return the process group ID of the calling process. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetpgid\fR() +shall return a process group ID. Otherwise, it shall return +(\fBpid_t\fP)\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetpgid\fR() +function shall fail if: +.TP +.BR EPERM +The process whose process ID is equal to +.IR pid +is not in the same session as the calling process, and the +implementation does not allow access to the process group ID of that +process from the calling process. +.TP +.BR ESRCH +There is no process with a process ID equal to +.IR pid . +.P +The +\fIgetpgid\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR pid +argument is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpgrp.3p b/upstream/archlinux/man3p/getpgrp.3p new file mode 100644 index 00000000..d4a547c2 --- /dev/null +++ b/upstream/archlinux/man3p/getpgrp.3p @@ -0,0 +1,82 @@ +'\" et +.TH GETPGRP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpgrp +\(em get the process group ID of the calling process +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getpgrp(void); +.fi +.SH DESCRIPTION +The +\fIgetpgrp\fR() +function shall return the process group ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetpgrp\fR() +function shall always be successful and no return value is reserved +to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +4.3 BSD provides a +\fIgetpgrp\fR() +function that returns the process group ID +for a specified process. Although this function supports job +control, all +known job control shells always specify the calling +process with this function. Thus, the simpler System V +\fIgetpgrp\fR() +suffices, and the added complexity of the 4.3 BSD +\fIgetpgrp\fR() +is provided by the XSI extension +\fIgetpgid\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetppid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpid.3p b/upstream/archlinux/man3p/getpid.3p new file mode 100644 index 00000000..c1c4fcf9 --- /dev/null +++ b/upstream/archlinux/man3p/getpid.3p @@ -0,0 +1,71 @@ +'\" et +.TH GETPID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpid +\(em get the process ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getpid(void); +.fi +.SH DESCRIPTION +The +\fIgetpid\fR() +function shall return the process ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetpid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetppid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpmsg.3p b/upstream/archlinux/man3p/getpmsg.3p new file mode 100644 index 00000000..f5b046f5 --- /dev/null +++ b/upstream/archlinux/man3p/getpmsg.3p @@ -0,0 +1,42 @@ +'\" et +.TH GETPMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpmsg +\(em receive next message from a STREAMS file +.SH SYNOPSIS +.LP +.nf +#include +.P +int getpmsg(int \fIfildes\fP, struct strbuf *restrict \fIctlptr\fP, + struct strbuf *restrict \fIdataptr\fP, int *restrict \fIbandp\fP, + int *restrict \fIflagsp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetmsg\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getppid.3p b/upstream/archlinux/man3p/getppid.3p new file mode 100644 index 00000000..e18a13fc --- /dev/null +++ b/upstream/archlinux/man3p/getppid.3p @@ -0,0 +1,71 @@ +'\" et +.TH GETPPID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getppid +\(em get the parent process ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getppid(void); +.fi +.SH DESCRIPTION +The +\fIgetppid\fR() +function shall return the parent process ID of the calling process. +.SH "RETURN VALUE" +The +\fIgetppid\fR() +function shall always be successful and no return value is reserved to +indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpriority.3p b/upstream/archlinux/man3p/getpriority.3p new file mode 100644 index 00000000..cf042ef7 --- /dev/null +++ b/upstream/archlinux/man3p/getpriority.3p @@ -0,0 +1,237 @@ +'\" et +.TH GETPRIORITY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpriority, +setpriority +\(em get and set the nice value +.SH SYNOPSIS +.LP +.nf +#include +.P +int getpriority(int \fIwhich\fP, id_t \fIwho\fP); +int setpriority(int \fIwhich\fP, id_t \fIwho\fP, int \fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIgetpriority\fR() +function shall obtain the nice value of a process, process group, or +user. The +\fIsetpriority\fR() +function shall set the nice value of a process, process group, or user +to +.IR value +\c +{NZERO}. +.P +Target processes are specified by the values of the +.IR which +and +.IR who +arguments. The +.IR which +argument may be one of the following values: PRIO_PROCESS, PRIO_PGRP, +or PRIO_USER, indicating that the +.IR who +argument +is to be interpreted as a process ID, a process group ID, or an +effective user ID, respectively. A 0 value for the +.IR who +argument specifies the current process, process group, or user. +.P +The nice value set with +\fIsetpriority\fR() +shall be applied to the process. If the process is multi-threaded, +the nice value shall affect all system scope threads in the process. +.P +If more than one process is specified, +\fIgetpriority\fR() +shall return value +{NZERO} +less than the lowest nice value pertaining to any of the specified +processes, and +\fIsetpriority\fR() +shall set the nice values of all of the specified processes to +.IR value +\c +{NZERO}. +.P +The default nice value is +{NZERO}; +lower nice values shall cause more favorable scheduling. While the +range of valid nice values is [0,{NZERO}*2\-1], implementations may +enforce more restrictive limits. If +.IR value +\c +{NZERO} +is less than the system's lowest supported nice value, +\fIsetpriority\fR() +shall set the nice value to the lowest supported value; if +.IR value +\c +{NZERO} +is greater than the system's highest supported nice value, +\fIsetpriority\fR() +shall set the nice value to the highest supported value. +.P +Only a process with appropriate privileges can lower its nice value. +.P +Any processes or threads using SCHED_FIFO or SCHED_RR shall be +unaffected by a call to +\fIsetpriority\fR(). +This is not considered an error. A process which subsequently reverts +to SCHED_OTHER need not have its priority affected by such a +\fIsetpriority\fR() +call. +.P +The effect of changing the nice value may vary depending on the +process-scheduling algorithm in effect. +.P +Since +\fIgetpriority\fR() +can return the value \-1 upon successful completion, it is necessary to +set +.IR errno +to 0 prior to a call to +\fIgetpriority\fR(). +If +\fIgetpriority\fR() +returns the value \-1, then +.IR errno +can be checked to see if an error occurred or if the value is a +legitimate nice value. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetpriority\fR() +shall return an integer in the range \-{NZERO} to +{NZERO}\-1. +Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.P +Upon successful completion, +\fIsetpriority\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.br +.SH ERRORS +The +\fIgetpriority\fR() +and +\fIsetpriority\fR() +functions shall fail if: +.TP +.BR ESRCH +No process could be located using the +.IR which +and +.IR who +argument values specified. +.TP +.BR EINVAL +The value of the +.IR which +argument was not recognized, or the value of the +.IR who +argument is not a valid process ID, process group ID, or user ID. +.P +In addition, +\fIsetpriority\fR() +may fail if: +.TP +.BR EPERM +A process was located, but neither the real nor effective user ID of +the executing process match the effective user ID of the process whose +nice value is being changed. +.TP +.BR EACCES +A request was made to change the nice value to a lower numeric value +and the current process does not have appropriate privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using getpriority(\|)" +.P +The following example returns the current scheduling priority for the +process ID returned by the call to +\fIgetpid\fR(). +.sp +.RS 4 +.nf + +#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int ret; +.P +pid = getpid(); +ret = getpriority(which, pid); +.fi +.P +.RE +.SS "Using setpriority(\|)" +.P +The following example sets the priority for the current process ID to +\-20. +.sp +.RS 4 +.nf + +#include +\&... +int which = PRIO_PROCESS; +id_t pid; +int priority = -20; +int ret; +.P +pid = getpid(); +ret = setpriority(which, pid, priority); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIgetpriority\fR() +and +\fIsetpriority\fR() +functions work with an offset nice value (nice value \-{NZERO}). The +nice value is in the range [0,2*{NZERO} \-1], while the return value +for +\fIgetpriority\fR() +and the third parameter for +\fIsetpriority\fR() +are in the range [\-{NZERO},{NZERO} \-1]. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fInice\fR\^(\|)", +.IR "\fIsched_get_priority_max\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getprotobyname.3p b/upstream/archlinux/man3p/getprotobyname.3p new file mode 100644 index 00000000..629c441b --- /dev/null +++ b/upstream/archlinux/man3p/getprotobyname.3p @@ -0,0 +1,44 @@ +'\" et +.TH GETPROTOBYNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getprotobyname, +getprotobynumber, +getprotent +\(em network protocol database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct protoent *getprotobyname(const char *\fIname\fP); +struct protoent *getprotobynumber(int \fIproto\fP); +struct protoent *getprotoent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendprotoent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpwent.3p b/upstream/archlinux/man3p/getpwent.3p new file mode 100644 index 00000000..26f651f6 --- /dev/null +++ b/upstream/archlinux/man3p/getpwent.3p @@ -0,0 +1,40 @@ +'\" et +.TH GETPWENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpwent +\(em get user database entry +.SH SYNOPSIS +.LP +.nf +#include +.P +struct passwd *getpwent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendpwent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpwnam.3p b/upstream/archlinux/man3p/getpwnam.3p new file mode 100644 index 00000000..33cedead --- /dev/null +++ b/upstream/archlinux/man3p/getpwnam.3p @@ -0,0 +1,248 @@ +'\" et +.TH GETPWNAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpwnam, +getpwnam_r +\(em search user database for a name +.SH SYNOPSIS +.LP +.nf +#include +.P +struct passwd *getpwnam(const char *\fIname\fP); +int getpwnam_r(const char *\fIname\fP, struct passwd *\fIpwd\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct passwd **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetpwnam\fR() +function shall search the user database for an entry with a matching +.IR name . +.P +The +\fIgetpwnam\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetpwnam\fR(). +If +\fIgetpwnam\fR() +returns a null pointer and +.IR errno +is non-zero, an error occurred. +.P +The +\fIgetpwnam_r\fR() +function shall update the +.BR passwd +structure pointed to by +.IR pwd +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the user database with a +matching +.IR name . +Storage referenced by the structure is allocated from the memory +provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +returns either \-1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetpwnam\fR() +function shall return a pointer to a +.BR "struct passwd" +with the structure as defined in +.IR +with a matching entry if found. A null pointer shall be returned if the +requested entry is not found, or an error occurs. If the requested +entry was not found, +.IR errno +shall not be changed. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetpwent\fR(), +\fIgetpwnam\fR(), +or +\fIgetpwuid\fR(). +The returned pointer, and pointers within the structure, might +also be invalidated if the calling thread is terminated. +.P +The +\fIgetpwnam_r\fR() +function shall return zero on success or if the requested entry +was not found and no error has occurred. If an error has +occurred, an error number shall be returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetpwnam\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIgetpwnam_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR passwd +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +may return \-1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetpwnam_r\fR(). +.sp +.RS 4 +.nf + +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= -1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct passwd result; +struct passwd *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getpwnam_r("someuser", &result, buffer, len, &resultp)) + =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi +.P +.RE +.SS "Getting an Entry for the Login Name" +.P +The following example uses the +\fIgetlogin\fR() +function to return the name of the user who logged in; this information +is passed to the +\fIgetpwnam\fR() +function to get the user database entry for that user. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +\&... +char *lgn; +struct passwd *pw; +\&... +if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) { + fprintf(stderr, "Get of user information failed.\en"); exit(1); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +returns the name associated with the effective user ID of the process; +\fIgetlogin\fR() +returns the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +returns the name associated with the real user ID of the process. +.P +The +\fIgetpwnam_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \-1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETPW_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwuid\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getpwuid.3p b/upstream/archlinux/man3p/getpwuid.3p new file mode 100644 index 00000000..49f7ff93 --- /dev/null +++ b/upstream/archlinux/man3p/getpwuid.3p @@ -0,0 +1,297 @@ +'\" et +.TH GETPWUID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getpwuid, +getpwuid_r +\(em search user database for a user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +struct passwd *getpwuid(uid_t \fIuid\fP); +int getpwuid_r(uid_t \fIuid\fP, struct passwd *\fIpwd\fP, char *\fIbuffer\fP, + size_t \fIbufsize\fP, struct passwd **\fIresult\fP); +.fi +.SH DESCRIPTION +The +\fIgetpwuid\fR() +function shall search the user database for an entry with a matching +.IR uid . +.P +The +\fIgetpwuid\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIgetpwuid\fR(). +If +\fIgetpwuid\fR() +returns a null pointer and +.IR errno +is set to non-zero, an error occurred. +.P +The +\fIgetpwuid_r\fR() +function shall update the +.BR passwd +structure pointed to by +.IR pwd +and store a pointer to that structure at the location pointed to by +.IR result . +The structure shall contain an entry from the user database with a +matching +.IR uid . +Storage referenced by the structure is allocated from the memory +provided with the +.IR buffer +parameter, which is +.IR bufsize +bytes in size. A call to +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +returns either \-1 without changing +.IR errno +or an initial value suggested for the size of this buffer. +A null pointer shall be returned at the location pointed to by +.IR result +on error or if the requested entry is not found. +.SH "RETURN VALUE" +The +\fIgetpwuid\fR() +function shall return a pointer to a +.BR "struct passwd" +with the structure as defined in +.IR +with a matching entry if found. A null pointer shall be returned if the +requested entry is not found, or an error occurs. If the requested +entry was not found, +.IR errno +shall not be changed. On error, +.IR errno +shall be set to indicate the error. +.P +The application shall not modify the structure to which the return +value points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIgetpwent\fR(), +\fIgetpwnam\fR(), +or +\fIgetpwuid\fR(). +The returned pointer, and pointers within the structure, might also +be invalidated if the calling thread is terminated. +.P +If successful, the +\fIgetpwuid_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EIO +An I/O error has occurred. +.TP +.BR EINTR +A signal was caught during +\fIgetpwuid\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIgetpwuid_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR buffer +and +.IR bufsize +to contain the data to be referenced by the resulting +.BR passwd +structure. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Note that +.IR sysconf (_SC_GETPW_R_SIZE_MAX) +may return \-1 if there is no hard limit on the size of the buffer +needed to store all the groups returned. This example shows how an +application can allocate a buffer of sufficient size to work with +\fIgetpwuid_r\fR(). +.sp +.RS 4 +.nf + +long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX); +size_t len; +if (initlen =\|= -1) + /* Default initial length. */ + len = 1024; +else + len = (size_t) initlen; +struct passwd result; +struct passwd *resultp; +char *buffer = malloc(len); +if (buffer =\|= NULL) + ...handle error... +int e; +while ((e = getpwuid_r(42, &result, buffer, len, &resultp)) =\|= ERANGE) + { + size_t newlen = 2 * len; + if (newlen < len) + ...handle error... + len = newlen; + char *newbuffer = realloc(buffer, len); + if (newbuffer =\|= NULL) + ...handle error... + buffer = newbuffer; + } +if (e != 0) + ...handle error... +free (buffer); +.fi +.P +.RE +.SS "Getting an Entry for the Root User" +.P +The following example gets the user database entry for the user with +user ID 0 (root). +.sp +.RS 4 +.nf + +#include +#include +\&... +uid_t id = 0; +struct passwd *pwd; +.P +pwd = getpwuid(id); +.fi +.P +.RE +.SS "Finding the Name for the Effective User ID" +.P +The following example defines +.IR pws +as a pointer to a structure of type +.BR passwd , +which is used to store the structure pointer returned by the call to +the +\fIgetpwuid\fR() +function. The +\fIgeteuid\fR() +function shall return the effective user ID of the calling process; +this is used as the search criteria for the +\fIgetpwuid\fR() +function. The call to +\fIgetpwuid\fR() +shall return a pointer to the structure containing that user ID value. +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +struct passwd *pws; +pws = getpwuid(geteuid()); +.fi +.P +.RE +.SS "Finding an Entry in the User Database" +.P +The following example uses +\fIgetpwuid\fR() +to search the user database for a user ID that was previously stored in +a +.BR stat +structure, then prints out the user name if it is found. If the user +is not found, the program prints the numeric value of the user ID for +the entry. +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +struct stat statbuf; +struct passwd *pwd; +\&... +if ((pwd = getpwuid(statbuf.st_uid)) != NULL) + printf(" %-8.8s", pwd->pw_name); +else + printf(" %-8d", statbuf.st_uid); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Three names associated with the current process can be determined: +.IR getpwuid (\c +\fIgeteuid\fR()) +returns the name associated with the effective user ID of the process; +\fIgetlogin\fR() +returns the name associated with the current login activity; and +.IR getpwuid (\c +\fIgetuid\fR()) +returns the name associated with the real user ID of the process. +.P +The +\fIgetpwuid_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.P +Portable applications should take into account that it is usual +for an implementation to return \-1 from +\fIsysconf\fR() +indicating that there is no maximum for _SC_GETPW_R_SIZE_MAX. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpwnam\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIgetlogin\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getrlimit.3p b/upstream/archlinux/man3p/getrlimit.3p new file mode 100644 index 00000000..e687ffeb --- /dev/null +++ b/upstream/archlinux/man3p/getrlimit.3p @@ -0,0 +1,252 @@ +'\" et +.TH GETRLIMIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getrlimit, +setrlimit +\(em control maximum resource consumption +.SH SYNOPSIS +.LP +.nf +#include +.P +int getrlimit(int \fIresource\fP, struct rlimit *\fIrlp\fP); +int setrlimit(int \fIresource\fP, const struct rlimit *\fIrlp\fP); +.fi +.SH DESCRIPTION +The +\fIgetrlimit\fR() +function shall get, and the +\fIsetrlimit\fR() +function shall set, limits on the consumption of a variety of +resources. +.P +Each call to either +\fIgetrlimit\fR() +or +\fIsetrlimit\fR() +identifies a specific resource to be operated upon as well as a +resource limit. A resource limit is represented by an +.BR rlimit +structure. The +.IR rlim_cur +member specifies the current or soft limit and the +.IR rlim_max +member specifies the maximum or hard limit. Soft limits may be changed +by a process to any value that is less than or equal to the hard +limit. A process may (irreversibly) lower its hard limit to any value +that is greater than or equal to the soft limit. Only a process with +appropriate privileges can raise a hard limit. Both hard and soft +limits can be changed in a single call to +\fIsetrlimit\fR() +subject to the constraints described above. +.P +The value RLIM_INFINITY, defined in +.IR , +shall be considered to be larger than any other limit value. If a +call to +\fIgetrlimit\fR() +returns RLIM_INFINITY for a resource, it means the implementation shall +not enforce limits on that resource. Specifying RLIM_INFINITY as any +resource limit value on a successful call to +\fIsetrlimit\fR() +shall inhibit enforcement of that resource limit. +.P +The following resources are defined: +.IP RLIMIT_CORE 14 +This is the maximum size of a +.BR core +file, in bytes, that may be created by a process. A limit of 0 shall +prevent the creation of a +.BR core +file. If this limit is exceeded, the writing of a +.BR core +file shall terminate at this size. +.IP RLIMIT_CPU 14 +This is the maximum amount of CPU time, in seconds, used by a process. +If this limit is exceeded, SIGXCPU shall be generated for the process. If +the process is catching or ignoring SIGXCPU, or all threads belonging +to that process are blocking SIGXCPU, the behavior is unspecified. +.IP RLIMIT_DATA 14 +This is the maximum size of a data segment of the process, in bytes. +If this limit is exceeded, the +\fImalloc\fR() +function shall fail with +.IR errno +set to +.BR [ENOMEM] . +.IP RLIMIT_FSIZE 14 +This is the maximum size of a file, in bytes, that may be created by a +process. If a write or truncate operation would cause this limit to be +exceeded, SIGXFSZ shall be generated for the thread. If the thread is +blocking, or +the process is catching or ignoring SIGXFSZ, continued attempts to +increase the size of a file from end-of-file to beyond the limit +shall fail with +.IR errno +set to +.BR [EFBIG] . +.IP RLIMIT_NOFILE 14 +This is a number one greater than the maximum value that the system may +assign to a newly-created descriptor. If this limit is exceeded, +functions that allocate a file descriptor shall fail with +.IR errno +set to +.BR [EMFILE] . +This limit constrains the number of file descriptors that a process may +allocate. +.IP RLIMIT_STACK 14 +This is the maximum size of the initial thread's stack, in bytes. The +implementation does not automatically grow the stack beyond this +limit. If this limit is exceeded, SIGSEGV shall be generated for the +thread. If the thread is blocking SIGSEGV, or the process is ignoring +or catching SIGSEGV and has not made arrangements to use an alternate +stack, the disposition of SIGSEGV shall be set to SIG_DFL before it is +generated. +.IP RLIMIT_AS 14 +This is the maximum size of total available memory of the process, in +bytes. If this limit is exceeded, the +\fImalloc\fR() +and +\fImmap\fR() +functions shall fail with +.IR errno +set to +.BR [ENOMEM] . +In addition, the automatic stack growth fails with the effects outlined +above. +.P +When using the +\fIgetrlimit\fR() +function, if a resource limit can be represented correctly in an object +of type +.BR rlim_t , +then its representation is returned; otherwise, if the value of the +resource limit is equal to that of the corresponding saved hard limit, +the value returned shall be RLIM_SAVED_MAX; otherwise, the value +returned shall be RLIM_SAVED_CUR. +.P +When using the +\fIsetrlimit\fR() +function, if the requested new limit is RLIM_INFINITY, the new limit +shall be ``no limit''; otherwise, if the +requested new limit is RLIM_SAVED_MAX, the new limit shall be the +corresponding saved hard limit; otherwise, if the requested new limit +is RLIM_SAVED_CUR, the new limit shall be the corresponding saved soft +limit; otherwise, the new limit shall be the requested value. In +addition, if the corresponding saved limit can be represented correctly +in an object of type +.BR rlim_t +then it shall be overwritten with the new limit. +.P +The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR is +unspecified unless a previous call to +\fIgetrlimit\fR() +returned that value as the soft or hard limit for the corresponding +resource limit. +.P +The determination of whether a limit can be correctly represented in an +object of type +.BR rlim_t +is implementation-defined. For example, some implementations permit a +limit whose value is greater than RLIM_INFINITY and others do not. +.P +The +.IR exec +family of functions shall cause resource limits to be saved. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetrlimit\fR() +and +\fIsetrlimit\fR() +shall return 0. Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetrlimit\fR() +and +\fIsetrlimit\fR() +functions shall fail if: +.TP +.BR EINVAL +An invalid +.IR resource +was specified; or in a +\fIsetrlimit\fR() +call, the new +.IR rlim_cur +exceeds the new +.IR rlim_max . +.TP +.BR EPERM +The limit specified to +\fIsetrlimit\fR() +would have raised the maximum limit value, and the calling process does +not have appropriate privileges. +.P +The +\fIsetrlimit\fR() +function may fail if: +.TP +.BR EINVAL +The limit specified cannot be lowered because current usage is already +higher than the limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If a process attempts to set the hard limit or soft limit for +RLIMIT_NOFILE to less than the value of +{_POSIX_OPEN_MAX} +from +.IR , +unexpected behavior may occur. +.P +If a process attempts to set the hard limit or soft limit for +RLIMIT_NOFILE to less than the highest currently open file descriptor ++1, unexpected behavior may occur. +.SH RATIONALE +It should be noted that RLIMIT_STACK applies ``at least'' to the stack +of the initial thread in the process, and not to the sum of all the +stacks in the process, as that would be very limiting unless the value +is so big as to provide no value at all with a single thread. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getrusage.3p b/upstream/archlinux/man3p/getrusage.3p new file mode 100644 index 00000000..eefbb2f0 --- /dev/null +++ b/upstream/archlinux/man3p/getrusage.3p @@ -0,0 +1,112 @@ +'\" et +.TH GETRUSAGE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getrusage +\(em get information about resource utilization +.SH SYNOPSIS +.LP +.nf +#include +.P +int getrusage(int \fIwho\fP, struct rusage *\fIr_usage\fP); +.fi +.SH DESCRIPTION +The +\fIgetrusage\fR() +function shall provide measures of the resources used by the current +process or its terminated and waited-for child processes. If the value +of the +.IR who +argument is RUSAGE_SELF, information shall be returned about resources +used by the current process. If the value of the +.IR who +argument is RUSAGE_CHILDREN, +information shall be returned about resources used by the terminated and +waited-for children of the current process. If the child is never +waited for (for example, if the parent has SA_NOCLDWAIT set or sets +SIGCHLD to SIG_IGN), the resource +information for the child process is discarded and not included in the +resource information provided by +\fIgetrusage\fR(). +.P +The +.IR r_usage +argument is a pointer to an object of type +.BR "struct rusage" +in which the returned information is stored. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetrusage\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetrusage\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR who +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using getrusage(\|)" +.P +The following example returns information about the resources used by +the current process. +.sp +.RS 4 +.nf + +#include +\&... +int who = RUSAGE_SELF; +struct rusage usage; +int ret; +.P +ret = getrusage(who, &usage); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexit\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/gets.3p b/upstream/archlinux/man3p/gets.3p new file mode 100644 index 00000000..9c07682e --- /dev/null +++ b/upstream/archlinux/man3p/gets.3p @@ -0,0 +1,137 @@ +'\" et +.TH GETS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +gets +\(em get a string from a +.IR stdin +stream +.SH SYNOPSIS +.LP +.nf +#include +.P +char *gets(char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIgets\fR() +function shall read bytes from the standard input stream, +.IR stdin , +into the array pointed to by +.IR s , +until a + +is read or an end-of-file condition is encountered. Any + +shall be discarded and a null byte shall be placed immediately +after the last byte read into the array. +.P +The +\fIgets\fR() +function may mark the last data access timestamp of +the file associated with +.IR stream +for update. The last data access timestamp shall be +marked for update by the first successful execution of +\fIfgetc\fR(), +\fIfgets\fR(), +\fIfread\fR(), +\fIfscanf\fR(), +\fIgetc\fR(), +\fIgetchar\fR(), +\fIgetdelim\fR(), +\fIgetline\fR(), +\fIgets\fR(), +or +\fIscanf\fR() +using +.IR stream +that returns data not supplied by a prior call to +\fIungetc\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIgets\fR() +shall return +.IR s . +If the end-of-file indicator for the stream is set, or if the stream +is at end-of-file, the end-of-file indicator for the +stream shall be set and +\fIgets\fR() +shall return a null pointer. If a read error occurs, the error indicator +for the stream shall be set, +\fIgets\fR() +shall return a null pointer, +and set +.IR errno +to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfgetc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Reading a line that overflows the array pointed to by +.IR s +results in undefined behavior. The use of +\fIfgets\fR() +is recommended. +.P +Since the user cannot specify the length of the buffer passed to +\fIgets\fR(), +use of this function is discouraged. The length of the string read is +unlimited. It is possible to overflow this buffer in such a way as to +cause applications to fail, or possible system security violations. +.P +Applications should use the +\fIfgets\fR() +function instead of the obsolescent +\fIgets\fR() +function. +.SH RATIONALE +The standard developers decided to mark the +\fIgets\fR() +function as obsolescent even though it is in the ISO\ C standard due to the +possibility of buffer overflow. +.SH "FUTURE DIRECTIONS" +The +\fIgets\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfgets\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getservbyname.3p b/upstream/archlinux/man3p/getservbyname.3p new file mode 100644 index 00000000..58d130c2 --- /dev/null +++ b/upstream/archlinux/man3p/getservbyname.3p @@ -0,0 +1,44 @@ +'\" et +.TH GETSERVBYNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getservbyname, +getservbyport, +getservent +\(em network services database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +struct servent *getservbyname(const char *\fIname\fP, const char *\fIproto\fP); +struct servent *getservbyport(int \fIport\fP, const char *\fIproto\fP); +struct servent *getservent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendservent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getsid.3p b/upstream/archlinux/man3p/getsid.3p new file mode 100644 index 00000000..c3433134 --- /dev/null +++ b/upstream/archlinux/man3p/getsid.3p @@ -0,0 +1,88 @@ +'\" et +.TH GETSID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getsid +\(em get the process group ID of a session leader +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t getsid(pid_t \fIpid\fP); +.fi +.SH DESCRIPTION +The +\fIgetsid\fR() +function shall obtain the process group ID of the process that is the +session leader of the process specified by +.IR pid . +If +.IR pid +is (\fBpid_t\fR)0, it specifies the calling process. +.SH "RETURN VALUE" +Upon successful completion, +\fIgetsid\fR() +shall return the process group ID of the session leader of the specified +process. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgetsid\fR() +function shall fail if: +.TP +.BR EPERM +The process specified by +.IR pid +is not in the same session as the calling process, and the +implementation does not allow access to the process group ID of the +session leader of that process from the calling process. +.TP +.BR ESRCH +There is no process with a process ID equal to +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getsockname.3p b/upstream/archlinux/man3p/getsockname.3p new file mode 100644 index 00000000..3f9b4a06 --- /dev/null +++ b/upstream/archlinux/man3p/getsockname.3p @@ -0,0 +1,123 @@ +'\" et +.TH GETSOCKNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getsockname +\(em get the socket name +.SH SYNOPSIS +.LP +.nf +#include +.P +int getsockname(int \fIsocket\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIgetsockname\fR() +function shall retrieve the locally-bound name of the specified socket, +store this address in the +.BR sockaddr +structure pointed to by the +.IR address +argument, and store the length of this address in the object pointed +to by the +.IR address_len +argument. +.P +The +.IR address_len +argument points to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the socket has not been bound to a local name, the value stored in +the object pointed to by +.IR address +is unspecified. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned, the +.IR address +argument shall point to the address of the socket, and the +.IR address_len +argument shall point to the length of the address. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetsockname\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The operation is not supported for this socket's protocol. +.P +The +\fIgetsockname\fR() +function may fail if: +.TP +.BR EINVAL +The socket has been shut down. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to complete the +function. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIgetpeername\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.br +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getsockopt.3p b/upstream/archlinux/man3p/getsockopt.3p new file mode 100644 index 00000000..efd48f3e --- /dev/null +++ b/upstream/archlinux/man3p/getsockopt.3p @@ -0,0 +1,146 @@ +'\" et +.TH GETSOCKOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getsockopt +\(em get the socket options +.SH SYNOPSIS +.LP +.nf +#include +.P +int getsockopt(int \fIsocket\fP, int \fIlevel\fP, int \fIoption_name,\fP + void *restrict \fIoption_value\fP, socklen_t *restrict \fIoption_len\fP); +.fi +.SH DESCRIPTION +The +\fIgetsockopt\fR() +function manipulates options associated with a socket. +.P +The +\fIgetsockopt\fR() +function shall retrieve the value for the option specified by the +.IR option_name +argument for the socket specified by the +.IR socket +argument. If the size of the option value is greater than +.IR option_len , +the value stored in the object pointed to by the +.IR option_value +argument shall be silently truncated. Otherwise, the object pointed to +by the +.IR option_len +argument shall be modified to indicate the actual length of the value. +.P +The +.IR level +argument specifies the protocol level at which the option resides. To +retrieve options at the socket level, specify the +.IR level +argument as SOL_SOCKET. To retrieve options at other levels, supply the +appropriate level identifier for the protocol controlling the option. +For example, to indicate that an option is interpreted by the TCP +(Transmission Control Protocol), set +.IR level +to IPPROTO_TCP as defined in the +.IR +header. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIgetsockopt\fR() +function. +.P +The +.IR option_name +argument specifies a single option to be retrieved. It can be one of +the socket-level options defined in +.IR "\fB\fP" +and described in +.IR "Section 2.10.16" ", " "Use of Options". +.SH "RETURN VALUE" +Upon successful completion, +\fIgetsockopt\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIgetsockopt\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINVAL +The specified option is invalid at the specified socket level. +.TP +.BR ENOPROTOOPT +.br +The option is not supported by the protocol. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.P +The +\fIgetsockopt\fR() +function may fail if: +.TP +.BR EACCES +The calling process does not have appropriate privileges. +.TP +.BR EINVAL +The socket has been shut down. +.TP +.BR ENOBUFS +Insufficient resources are available in the system to complete the +function. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.10.16" ", " "Use of Options", +.IR "\fIbind\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getsubopt.3p b/upstream/archlinux/man3p/getsubopt.3p new file mode 100644 index 00000000..69a0a916 --- /dev/null +++ b/upstream/archlinux/man3p/getsubopt.3p @@ -0,0 +1,298 @@ +'\" et +.TH GETSUBOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getsubopt +\(em parse suboption arguments from a string +.SH SYNOPSIS +.LP +.nf +#include +.P +int getsubopt(char **\fIoptionp\fP, char * const *\fIkeylistp\fP, char **\fIvaluep\fP); +.fi +.SH DESCRIPTION +The +\fIgetsubopt\fR() +function shall parse suboption arguments in a flag argument. Such +options often result from the use of +\fIgetopt\fR(). +.P +The +\fIgetsubopt\fR() +argument +.IR optionp +is a pointer to a pointer to the option argument string. The suboption +arguments shall be separated by + +characters and each may consist of either a single token, or a token-value +pair separated by an +. +.P +The +.IR keylistp +argument shall be a pointer to a vector of strings. The end of the +vector is identified by a null pointer. Each entry in the vector is one +of the possible tokens that might be found in *\fIoptionp\fP. Since + +characters delimit suboption arguments in +.IR optionp , +they should not appear in any of the strings pointed to by +.IR keylistp . +Similarly, because an + +separates a token from its value, the application should not include an + +in any of the strings pointed to by +.IR keylistp . +The +\fIgetsubopt\fR() +function shall not modify the +.IR keylistp +vector. +.P +The +.IR valuep +argument is the address of a value string pointer. +.P +If a + +appears in +.IR optionp , +it shall be interpreted as a suboption separator. After + +characters have been processed, if there are one or more + +characters in a suboption string, the first + +in any suboption string shall be interpreted as a separator between a +token and a value. Subsequent + +characters in a suboption string shall be interpreted as part of the +value. +.P +If the string at *\fIoptionp\fP contains only one suboption argument +(equivalently, no + +characters), +\fIgetsubopt\fR() +shall update *\fIoptionp\fP to point to the null character at the end of +the string. Otherwise, it shall isolate the suboption argument by +replacing the + +separator with a null character, and shall update *\fIoptionp\fP to point +to the start of the next suboption argument. If the suboption argument +has an associated value (equivalently, contains an +), +\fIgetsubopt\fR() +shall update *\fIvaluep\fP to point to the value's first character. +Otherwise, it shall set *\fIvaluep\fP to a null pointer. The calling +application may use this information to determine whether the presence +or absence of a value for the suboption is an error. +.P +Additionally, when +\fIgetsubopt\fR() +fails to match the suboption argument with a token in the +.IR keylistp +array, the calling application should decide if this is an error, or if +the unrecognized option should be processed in another way. +.SH "RETURN VALUE" +The +\fIgetsubopt\fR() +function shall return the index of the matched token string, or \-1 +if no token strings were matched. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Parsing Suboptions" +.P +The following example uses the +\fIgetsubopt\fR() +function to parse a +.IR value +argument in the +.IR optarg +external variable returned by a call to +\fIgetopt\fR(). +.sp +.RS 4 +.nf + +#include +#include +#include +.P +int do_all; +const char *type; +int read_size; +int write_size; +int read_only; +.P +enum +{ + RO_OPTION = 0, + RW_OPTION, + READ_SIZE_OPTION, + WRITE_SIZE_OPTION +}; +.P +const char *mount_opts[] = +{ + [RO_OPTION] = "ro", + [RW_OPTION] = "rw", + [READ_SIZE_OPTION] = "rsize", + [WRITE_SIZE_OPTION] = "wsize", + NULL +}; +.P +int +main(int argc, char *argv[]) +{ + char *subopts, *value; + int opt; +.P + while ((opt = getopt(argc, argv, "at:o:")) != -1) + switch(opt) + { + case \(aqa\(aq: + do_all = 1; + break; + case \(aqt\(aq: + type = optarg; + break; + case \(aqo\(aq: + subopts = optarg; + while (*subopts != \(aq\0\(aq) + { + char *saved = subopts; + switch(getsubopt(&subopts, (char **)mount_opts, + &value)) + { + case RO_OPTION: + read_only = 1; + break; + case RW_OPTION: + read_only = 0; + break; + case READ_SIZE_OPTION: + if (value == NULL) + abort(); + read_size = atoi(value); + break; + case WRITE_SIZE_OPTION: + if (value == NULL) + abort(); + write_size = atoi(value); + break; + default: + /* Unknown suboption. */ + printf("Unknown suboption `%s\(aq\en", saved); + abort(); + } + } + break; + default: + abort(); + } +.P + /* Do the real work. */ +.P + return 0; +} +.fi +.P +.RE +.P +If the above example is invoked with: +.sp +.RS 4 +.nf + +program -o ro,rsize=512 +.fi +.P +.RE +.P +then after option parsing, the variable +.IR do_all +will be 0, +.IR type +will be a null pointer, +.IR read_size +will be 512, +.IR write_size +will be 0, and +.IR read_only +will be 1. If it is invoked with: +.sp +.RS 4 +.nf + +program -o oops +.fi +.P +.RE +.P +it will print: +.sp +.RS 4 +.nf + +"Unknown suboption `oops\(aq" +.fi +.P +.RE +.P +before aborting. +.SH "APPLICATION USAGE" +The value of *\fIvaluep\fR when +\fIgetsubopt\fR() +returns \-1 is unspecified. Historical implementations provide various +incompatible extensions to allow an application to access the suboption +text that was not found in the +.IR keylistp +array. +.SH RATIONALE +The +.IR keylistp +argument of +\fIgetsubopt\fR() +is typed as +.BR "char * const *" +to match historical practice. However, the standard is clear that +implementations will not modify either the array or the strings contained +in the array, as if the argument had been typed +.BR "const char * const *" . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/gettimeofday.3p b/upstream/archlinux/man3p/gettimeofday.3p new file mode 100644 index 00000000..d8d9a8e2 --- /dev/null +++ b/upstream/archlinux/man3p/gettimeofday.3p @@ -0,0 +1,79 @@ +'\" et +.TH GETTIMEOFDAY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +gettimeofday +\(em get the date and time +.SH SYNOPSIS +.LP +.nf +#include +.P +int gettimeofday(struct timeval *restrict \fItp\fP, void *restrict \fItzp\fP); +.fi +.SH DESCRIPTION +The +\fIgettimeofday\fR() +function shall obtain the current time, expressed as seconds and +microseconds since the Epoch, and store it in the +.BR timeval +structure pointed to by +.IR tp . +The resolution of the system clock is unspecified. +.P +If +.IR tzp +is not a null pointer, the behavior is unspecified. +.SH "RETURN VALUE" +The +\fIgettimeofday\fR() +function shall return 0 and no value shall be reserved to indicate +an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications should use the +\fIclock_gettime\fR() +function instead of the obsolescent +\fIgettimeofday\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIgettimeofday\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIctime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getuid.3p b/upstream/archlinux/man3p/getuid.3p new file mode 100644 index 00000000..ae65b708 --- /dev/null +++ b/upstream/archlinux/man3p/getuid.3p @@ -0,0 +1,99 @@ +'\" et +.TH GETUID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getuid +\(em get a real user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +uid_t getuid(void); +.fi +.SH DESCRIPTION +The +\fIgetuid\fR() +function shall return the real user ID of the calling process. +The +\fIgetuid\fR() +function shall not modify +.IR errno . +.SH "RETURN VALUE" +The +\fIgetuid\fR() +function shall always be successful and no return value is reserved to +indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting the Effective User ID to the Real User ID" +.P +The following example sets the effective user ID of the calling +process to the real user ID. +.sp +.RS 4 +.nf + +#include +\&... +seteuid(getuid()); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +In a conforming environment, +\fIgetuid\fR() +will always succeed. It is possible for implementations to provide +an extension where a process in a non-conforming environment +will not be associated with a user or group ID. It is recommended +that such implementations return (\c +.BR uid_t )\-1 +and set +.IR errno +to indicate such an environment; doing so does not violate +this standard, since such an environment is already an extension. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getutxent.3p b/upstream/archlinux/man3p/getutxent.3p new file mode 100644 index 00000000..a276faf2 --- /dev/null +++ b/upstream/archlinux/man3p/getutxent.3p @@ -0,0 +1,44 @@ +'\" et +.TH GETUTXENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getutxent, +getutxid, +getutxline +\(em get user accounting database entries +.SH SYNOPSIS +.LP +.nf +#include +.P +struct utmpx *getutxent(void); +struct utmpx *getutxid(const struct utmpx *\fIid\fP); +struct utmpx *getutxline(const struct utmpx *\fIline\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendutxent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getwc.3p b/upstream/archlinux/man3p/getwc.3p new file mode 100644 index 00000000..cd13f6f8 --- /dev/null +++ b/upstream/archlinux/man3p/getwc.3p @@ -0,0 +1,82 @@ +'\" et +.TH GETWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getwc +\(em get a wide character from a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t getwc(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIgetwc\fR() +function shall be equivalent to +\fIfgetwc\fR(), +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since it may be implemented as a macro, +\fIgetwc\fR() +may treat incorrectly a +.IR stream +argument with side-effects. In particular, +\fIgetwc\fR(*\fIf\fR\(pl\(pl) does not necessarily work as expected. +Therefore, use of this function is not recommended; +\fIfgetwc\fR() +should be used instead. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/getwchar.3p b/upstream/archlinux/man3p/getwchar.3p new file mode 100644 index 00000000..8f719206 --- /dev/null +++ b/upstream/archlinux/man3p/getwchar.3p @@ -0,0 +1,81 @@ +'\" et +.TH GETWCHAR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +getwchar +\(em get a wide character from a +.IR stdin +stream +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t getwchar(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIgetwchar\fR() +function shall be equivalent to \fIgetwc\fP(\fIstdin\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfgetwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the +.BR wint_t +value returned by +\fIgetwchar\fR() +is stored into a variable of type +.BR wchar_t +and then compared against the +.BR wint_t +macro WEOF, the result may be incorrect. Only the +.BR wint_t +type is guaranteed to be able to represent any wide character and +WEOF. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfgetwc\fR\^(\|)", +.IR "\fIgetwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/glob.3p b/upstream/archlinux/man3p/glob.3p new file mode 100644 index 00000000..99b4aed5 --- /dev/null +++ b/upstream/archlinux/man3p/glob.3p @@ -0,0 +1,450 @@ +'\" et +.TH GLOB "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +glob, +globfree +\(em generate pathnames matching a pattern +.SH SYNOPSIS +.LP +.nf +#include +.P +int glob(const char *restrict \fIpattern\fP, int \fIflags\fP, + int(*\fIerrfunc\fP)(const char *\fIepath\fP, int \fIeerrno\fP), + glob_t *restrict \fIpglob\fP); +void globfree(glob_t *\fIpglob\fP); +.fi +.SH DESCRIPTION +The +\fIglob\fR() +function is a pathname generator that shall implement the rules +defined in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13" ", " "Pattern Matching Notation", +with optional support for rule 3 in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion". +.P +The structure type +.BR glob_t +is defined in +.IR +and includes at least the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +size_t!gl_pathc!Count of paths matched by \fIpattern\fP. +char **!gl_pathv!Pointer to a list of matched pathnames. +size_t!gl_offs!T{ +Slots to reserve at the beginning of \fIgl_pathv\fP. +T} +.TE +.P +The argument +.IR pattern +is a pointer to a pathname pattern to be expanded. The +\fIglob\fR() +function shall match all accessible pathnames against this pattern and +develop a list of all pathnames that match. In order to have access to +a pathname, +\fIglob\fR() +requires search permission on every component of a path except the +last, and read permission on each directory of any filename component +of +.IR pattern +that contains any of the following special characters: +.BR '*' , +.BR '?' , +and +.BR '[' . +.P +The +\fIglob\fR() +function shall store the number of matched pathnames into +\fIpglob\fP\->\fIgl_pathc\fP and a pointer to a list of pointers to +pathnames into \fIpglob\fP\->\fIgl_pathv\fP. The pathnames shall be in +sort order as defined by the current setting of the +.IR LC_COLLATE +category; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 7.3.2" ", " "LC_COLLATE". +The first pointer after the last pathname shall be a null pointer. If +the pattern does not match any pathnames, the returned number of matched +paths is set to 0, and the contents of \fIpglob\fP\->\fIgl_pathv\fP +are implementation-defined. +.P +It is the caller's responsibility to create the structure pointed to by +.IR pglob . +The +\fIglob\fR() +function shall allocate other space as needed, including the memory +pointed to by +.IR gl_pathv . +The +\fIglobfree\fR() +function shall free any space associated with +.IR pglob +from a previous call to +\fIglob\fR(). +.P +The +.IR flags +argument is used to control the behavior of +\fIglob\fR(). +The value of +.IR flags +is a bitwise-inclusive OR of zero or more of the following +constants, which are defined in +.IR : +.IP GLOB_APPEND 14 +Append pathnames generated to the ones from a previous call to +\fIglob\fR(). +.IP GLOB_DOOFFS 14 +Make use of \fIpglob\fP\->\fIgl_offs\fP. If this flag is set, +\fIpglob\fP\->\fIgl_offs\fP is used to specify how many null pointers +to add to the beginning of \fIpglob\fP\->\fIgl_pathv\fP. In other +words, \fIpglob\fP\->\fIgl_pathv\fP shall point to +\fIpglob\fP\->\fIgl_offs\fP null pointers, followed by +\fIpglob\fP\->\fIgl_pathc\fP pathname pointers, followed by a null +pointer. +.IP GLOB_ERR 14 +Cause +\fIglob\fR() +to return when it encounters a directory that it cannot open or read. +Ordinarily, +\fIglob\fR() +continues to find matches. +.IP GLOB_MARK 14 +Each pathname that is a directory that matches +.IR pattern +shall have a + +appended. +.IP GLOB_NOCHECK 14 +Supports rule 3 in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion". +If +.IR pattern +does not match any pathname, then +\fIglob\fR() +shall return a list consisting of only +.IR pattern , +and the number of matched pathnames is 1. +.IP GLOB_NOESCAPE 14 +Disable backslash escaping. +.IP GLOB_NOSORT 14 +Ordinarily, +\fIglob\fR() +sorts the matching pathnames according to the current setting of the +.IR LC_COLLATE +category; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 7.3.2" ", " "LC_COLLATE". +When this flag is used, the order of pathnames returned is unspecified. +.P +The GLOB_APPEND +flag can be used to append a new set of pathnames to those found in a +previous call to +\fIglob\fR(). +The following rules apply to applications when two or more calls to +\fIglob\fR() +are made with the same value of +.IR pglob +and without intervening calls to +\fIglobfree\fR(): +.IP " 1." 4 +The first such call shall not set GLOB_APPEND. All subsequent calls +shall set it. +.IP " 2." 4 +All the calls shall set GLOB_DOOFFS, or all shall not set it. +.IP " 3." 4 +After the second call, \fIpglob\fP\->\fIgl_pathv\fP points to a list +containing the following: +.RS 4 +.IP " a." 4 +Zero or more null pointers, as specified by GLOB_DOOFFS and +\fIpglob\fP\->\fIgl_offs\fP. +.IP " b." 4 +Pointers to the pathnames that were in the +\fIpglob\fP\->\fIgl_pathv\fP list before the call, in the same order +as before. +.IP " c." 4 +Pointers to the new pathnames generated by the second call, in the +specified order. +.RE +.IP " 4." 4 +The count returned in \fIpglob\fP\->\fIgl_pathc\fP shall be the total +number of pathnames from the two calls. +.IP " 5." 4 +The application can change any of the fields after a call to +\fIglob\fR(). +If it does, the application shall reset them to the original value +before a subsequent call, using the same +.IR pglob +value, to +\fIglobfree\fR() +or +\fIglob\fR() +with the GLOB_APPEND flag. +.P +If, during the search, a directory is encountered that cannot be opened +or read and +.IR errfunc +is not a null pointer, +\fIglob\fR() +calls +\fI(\fR()*errfunc ) +with two arguments: +.IP " 1." 4 +The +.IR epath +argument is a pointer to the path that failed. +.IP " 2." 4 +The +.IR eerrno +argument is the value of +.IR errno +from the failure, as set by +\fIopendir\fR(), +\fIreaddir\fR(), +or +\fIstat\fR(). +(Other values may be used to report other errors not explicitly +documented for those functions.) +.P +If +\fI(\fR()*errfunc ) +is called and returns non-zero, or if the GLOB_ERR flag is set in +.IR flags , +\fIglob\fR() +shall stop the scan and return GLOB_ABORTED after setting +.IR gl_pathc +and +.IR gl_pathv +in +.IR pglob +to reflect the paths already scanned. If GLOB_ERR is not set and +either +.IR errfunc +is a null pointer or +\fI(\fR()*errfunc ) +returns 0, the error shall be ignored. +.P +The +\fIglob\fR() +function shall not fail because of large files. +.SH "RETURN VALUE" +Upon successful completion, +\fIglob\fR() +shall return 0. The argument \fIpglob\fP\->\fIgl_pathc\fP shall +return the number of matched pathnames and the argument +\fIpglob\fP\->\fIgl_pathv\fP shall contain a pointer to a +null-terminated list of matched and sorted pathnames. However, if +\fIpglob\fP\->\fIgl_pathc\fP is 0, the content of +\fIpglob\fP\->\fIgl_pathv\fP is undefined. +.P +The +\fIglobfree\fR() +function shall not return a value. +.P +If +\fIglob\fR() +terminates due to an error, it shall return one of the non-zero +constants defined in +.IR . +The arguments \fIpglob\fP\->\fIgl_pathc\fP and +\fIpglob\fP\->\fIgl_pathv\fP are still set as defined above. +.SH ERRORS +The +\fIglob\fR() +function shall fail and return the corresponding value if: +.IP GLOB_ABORTED 14 +The scan was stopped because GLOB_ERR was set or +\fI(\fR()*errfunc ) +returned non-zero. +.IP GLOB_NOMATCH 14 +The pattern does not match any existing pathname, and GLOB_NOCHECK was +not set in flags. +.IP GLOB_NOSPACE 14 +An attempt to allocate memory failed. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +One use of the GLOB_DOOFFS flag is by applications that +build an argument list for use with +\fIexecv\fR(), +\fIexecve\fR(), +or +\fIexecvp\fR(). +Suppose, for example, that an application wants to do the equivalent of: +.sp +.RS 4 +.nf + +ls -l *.c +.fi +.P +.RE +.P +but for some reason: +.sp +.RS 4 +.nf + +system("ls -l *.c") +.fi +.P +.RE +.P +is not acceptable. The application could obtain approximately the same +result using the sequence: +.sp +.RS 4 +.nf + +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +globbuf.gl_pathv[0] = "ls"; +globbuf.gl_pathv[1] = "-l"; +execvp("ls", &globbuf.gl_pathv[0]); +.fi +.P +.RE +.P +Using the same example: +.sp +.RS 4 +.nf + +ls -l *.c *.h +.fi +.P +.RE +.P +could be approximately simulated using GLOB_APPEND as follows: +.sp +.RS 4 +.nf + +globbuf.gl_offs = 2; +glob("*.c", GLOB_DOOFFS, NULL, &globbuf); +glob("*.h", GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +This function is not provided for the purpose of enabling utilities to +perform pathname expansion on their arguments, as this operation is +performed by the shell, and utilities are explicitly not expected to +redo this. Instead, it is provided for applications that need to do +pathname expansion on strings obtained from other sources, such as a +pattern typed by a user or read from a file. +.P +If a utility needs to see if a pathname matches a given pattern, it can +use +\fIfnmatch\fR(). +.P +Note that +.IR gl_pathc +and +.IR gl_pathv +have meaning even if +\fIglob\fR() +fails. This allows +\fIglob\fR() +to report partial results in the event of an error. However, if +.IR gl_pathc +is 0, +.IR gl_pathv +is unspecified even if +\fIglob\fR() +did not return an error. +.P +The GLOB_NOCHECK option could be used when an application wants to +expand a pathname if wildcards are specified, but wants to treat the +pattern as just a string otherwise. The +.IR sh +utility might use this for option-arguments, for example. +.P +The new pathnames generated by a subsequent call with GLOB_APPEND are +not sorted together with the previous pathnames. This mirrors the way +that the shell handles pathname expansion when multiple expansions are +done on a command line. +.P +Applications that need tilde and parameter expansion should use +\fIwordexp\fR(). +.SH RATIONALE +It was claimed that the GLOB_DOOFFS flag is unnecessary because it +could be simulated using: +.sp +.RS 4 +.nf + +new = (char **)malloc((n + pglob->gl_pathc + 1) + * sizeof(char *)); +(void) memcpy(new+n, pglob->gl_pathv, + pglob->gl_pathc * sizeof(char *)); +(void) memset(new, 0, n * sizeof(char *)); +free(pglob->gl_pathv); +pglob->gl_pathv = new; +.fi +.P +.RE +.P +However, this assumes that the memory pointed to by +.IR gl_pathv +is a block that was separately created using +\fImalloc\fR(). +This is not necessarily the case. An application should make no +assumptions about how the memory referenced by fields in +.IR pglob +was allocated. It might have been obtained from +\fImalloc\fR() +in a large chunk and then carved up within +\fIglob\fR(), +or it might have been created using a different memory allocator. It +is not the intent of the standard developers to specify or imply how +the memory used by +\fIglob\fR() +is managed. +.P +The GLOB_APPEND flag would be used when an application wants to expand +several different patterns into a single list. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfnmatch\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "Section 2.6" ", " "Word Expansions" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 7.3.2" ", " "LC_COLLATE", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/gmtime.3p b/upstream/archlinux/man3p/gmtime.3p new file mode 100644 index 00000000..8b53a49d --- /dev/null +++ b/upstream/archlinux/man3p/gmtime.3p @@ -0,0 +1,154 @@ +'\" et +.TH GMTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +gmtime, +gmtime_r +\(em convert a time value to a broken-down UTC time +.SH SYNOPSIS +.LP +.nf +#include +.P +struct tm *gmtime(const time_t *\fItimer\fP); +struct tm *gmtime_r(const time_t *restrict \fItimer\fP, + struct tm *restrict \fIresult\fP); +.fi +.SH DESCRIPTION +For +\fIgmtime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIgmtime\fR() +function shall convert the time in seconds since the Epoch pointed to by +.IR timer +into a broken-down time, expressed as Coordinated Universal Time +(UTC). +.P +The relationship between a time in seconds since the Epoch used as an +argument to +\fIgmtime\fR() +and the +.BR tm +structure (defined in the +.IR +header) is that the result shall be as specified in the expression +given in the definition of seconds since the Epoch (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.16" ", " "Seconds Since the Epoch"), +where the names in the structure and in the expression correspond. +.P +The same relationship shall apply for +\fIgmtime_r\fR(). +.P +The +\fIgmtime\fR() +function need not be thread-safe. +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of type +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIgmtime_r\fR() +function shall convert the time in seconds since the Epoch pointed to by +.IR timer +into a broken-down time expressed as Coordinated Universal Time (UTC). +The broken-down time is stored in the structure referred to by +.IR result . +The +\fIgmtime_r\fR() +function shall also return the address of the same structure. +.SH "RETURN VALUE" +Upon successful completion, the +\fIgmtime\fR() +function shall return a pointer to a +.BR "struct tm" . +If an error is detected, +\fIgmtime\fR() +shall return a null pointer +and set +.IR errno +to indicate the error. +.P +Upon successful completion, +\fIgmtime_r\fR() +shall return the address of the structure pointed to by the argument +.IR result . +If an error is detected, +\fIgmtime_r\fR() +shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgmtime\fR() +and +\fIgmtime_r\fR() +functions shall fail if: +.TP +.BR EOVERFLOW +The result cannot be represented. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIgmtime_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.16" ", " "Seconds Since the Epoch", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/grantpt.3p b/upstream/archlinux/man3p/grantpt.3p new file mode 100644 index 00000000..6b49dcbb --- /dev/null +++ b/upstream/archlinux/man3p/grantpt.3p @@ -0,0 +1,95 @@ +'\" et +.TH GRANTPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +grantpt +\(em grant access to the slave pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include +.P +int grantpt(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIgrantpt\fR() +function shall change the mode and ownership of the slave pseudo-terminal +device associated with its master pseudo-terminal counterpart. The +.IR fildes +argument is a file descriptor that refers to a master +pseudo-terminal device. The user ID of the slave shall be set to the real +UID of the calling process and the group ID shall be set to an unspecified +group ID. The permission mode of the slave pseudo-terminal shall be set to +readable and writable by the owner, and writable by the group. +.P +The behavior of the +\fIgrantpt\fR() +function is unspecified if the application has installed a signal +handler to catch SIGCHLD signals. +.SH "RETURN VALUE" +Upon successful completion, +\fIgrantpt\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIgrantpt\fR() +function may fail if: +.TP +.BR EACCES +The corresponding slave pseudo-terminal device could not be accessed. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument is not associated with a master pseudo-terminal device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIposix_openpt\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/hcreate.3p b/upstream/archlinux/man3p/hcreate.3p new file mode 100644 index 00000000..8e41d25d --- /dev/null +++ b/upstream/archlinux/man3p/hcreate.3p @@ -0,0 +1,213 @@ +'\" et +.TH HCREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +hcreate, +hdestroy, +hsearch +\(em manage hash search table +.SH SYNOPSIS +.LP +.nf +#include +.P +int hcreate(size_t \fInel\fP); +void hdestroy(void); +ENTRY *hsearch(ENTRY \fIitem\fP, ACTION \fIaction\fP); +.fi +.SH DESCRIPTION +The +\fIhcreate\fR(), +\fIhdestroy\fR(), +and +\fIhsearch\fR() +functions shall manage hash search tables. +.P +The +\fIhcreate\fR() +function shall allocate sufficient space for the table, and the +application shall ensure it is called before +\fIhsearch\fR() +is used. The +.IR nel +argument is an estimate of the maximum number of entries that the table +shall contain. This number may be adjusted upward by the algorithm in +order to obtain certain mathematically favorable circumstances. +.P +The +\fIhdestroy\fR() +function shall dispose of the search table, and may be followed by +another call to +\fIhcreate\fR(). +After the call to +\fIhdestroy\fR(), +the data can no longer be considered accessible. +.P +The +\fIhsearch\fR() +function is a hash-table search routine. It shall return a pointer into a +hash table indicating the location at which an entry can be found. The +.IR item +argument is a structure of type +.BR ENTRY +(defined in the +.IR +header) containing two pointers: +.IR item.key +points to the comparison key (a +.BR "char *" ), +and +.IR item.data +(a +.BR "void *" ) +points to any other data to be associated with that key. The +comparison function used by +\fIhsearch\fR() +is +\fIstrcmp\fR(). +The +.IR action +argument is a member of an enumeration type +.BR ACTION +indicating the disposition of the entry if it cannot be found in the +table. ENTER indicates that the item should be inserted in the table +at an appropriate point. FIND indicates that no entry should be made. +Unsuccessful resolution is indicated by the return of a null pointer. +.P +These functions need not be thread-safe. +.SH "RETURN VALUE" +The +\fIhcreate\fR() +function shall return 0 if it cannot allocate sufficient space for the +table; otherwise, it shall return non-zero. +.P +The +\fIhdestroy\fR() +function shall not return a value. +.P +The +\fIhsearch\fR() +function shall return a null pointer if either the action is FIND and +the item could not be found or the action is ENTER and the table is +full. +.SH ERRORS +The +\fIhcreate\fR() +and +\fIhsearch\fR() +functions may fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following example reads in strings followed by two numbers and +stores them in a hash table, discarding duplicates. It then reads in +strings and finds the matching entry in the hash table and prints it +out. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +struct info { /* This is the info stored in the table */ + int age, room; /* other than the key. */ +}; +.P +#define NUM_EMPL 5000 /* # of elements in search table. */ +.P +int main(void) +{ + char string_space[NUM_EMPL*20]; /* Space to store strings. */ + struct info info_space[NUM_EMPL]; /* Space to store employee info. */ + char *str_ptr = string_space; /* Next space in string_space. */ + struct info *info_ptr = info_space; + /* Next space in info_space. */ + ENTRY item; + ENTRY *found_item; /* Name to look for in table. */ + char name_to_find[30]; +.P + int i = 0; +.P + /* Create table; no error checking is performed. */ + (void) hcreate(NUM_EMPL); + while (scanf("%s%d%d", str_ptr, &info_ptr->age, + &info_ptr->room) != EOF && i++ < NUM_EMPL) { +.P + /* Put information in structure, and structure in item. */ + item.key = str_ptr; + item.data = info_ptr; + str_ptr += strlen(str_ptr) + 1; + info_ptr++; +.P + /* Put item into table. */ + (void) hsearch(item, ENTER); + } +.P + /* Access table. */ + item.key = name_to_find; + while (scanf("%s", item.key) != EOF) { + if ((found_item = hsearch(item, FIND)) != NULL) { +.P + /* If item is in the table. */ + (void)printf("found %s, age = %d, room = %d\en", + found_item->key, + ((struct info *)found_item->data)->age, + ((struct info *)found_item->data)->room); + } else + (void)printf("no such employee %s\en", name_to_find); + } + return 0; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIhcreate\fR() +and +\fIhsearch\fR() +functions may use +\fImalloc\fR() +to allocate space. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbsearch\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/htonl.3p b/upstream/archlinux/man3p/htonl.3p new file mode 100644 index 00000000..9d176043 --- /dev/null +++ b/upstream/archlinux/man3p/htonl.3p @@ -0,0 +1,92 @@ +'\" et +.TH HTONL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +htonl, +htons, +ntohl, +ntohs +\(em convert values between host and network byte order +.SH SYNOPSIS +.LP +.nf +#include +.P +uint32_t htonl(uint32_t \fIhostlong\fP); +uint16_t htons(uint16_t \fIhostshort\fP); +uint32_t ntohl(uint32_t \fInetlong\fP); +uint16_t ntohs(uint16_t \fInetshort\fP); +.fi +.SH DESCRIPTION +These functions shall convert 16-bit and 32-bit quantities between +network byte order and host byte order. +.P +On some implementations, these functions are defined as macros. +.P +The +.BR uint32_t +and +.BR uint16_t +types are defined in +.IR . +.SH "RETURN VALUE" +The +\fIhtonl\fR() +and +\fIhtons\fR() +functions shall return the argument value converted from host to +network byte order. +.P +The +\fIntohl\fR() +and +\fIntohs\fR() +functions shall return the argument value converted from network to +host byte order. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +These functions are most often used in conjunction with IPv4 addresses +and ports as returned by +\fIgethostent\fR() +and +\fIgetservent\fR(). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendservent\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/hypot.3p b/upstream/archlinux/man3p/hypot.3p new file mode 100644 index 00000000..095a5721 --- /dev/null +++ b/upstream/archlinux/man3p/hypot.3p @@ -0,0 +1,158 @@ +'\" et +.TH HYPOT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +hypot, +hypotf, +hypotl +\(em Euclidean distance function +.SH SYNOPSIS +.LP +.nf +#include +.P +double hypot(double \fIx\fP, double \fIy\fP); +float hypotf(float \fIx\fP, float \fIy\fP); +long double hypotl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the value of the square root of +.IR x \s-3\u2\d\s+3+\c +.IR y \s-3\u2\d\s+3 +without undue overflow or underflow. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the length of +the hypotenuse of a right-angled triangle with sides of length +.IR x +and +.IR y . +.P +If the correct value would cause overflow, a range error shall occur +and +\fIhypot\fR(), +\fIhypotf\fR(), +and +\fIhypotl\fR() +shall return the value of the macro HUGE_VAL, HUGE_VALF, and HUGE_VALL, +respectively. +.P +If +.IR x +or +.IR y +is \(+-Inf, +Inf shall be returned (even if one of +.IR x +or +.IR y +is NaN). +.P +If +.IR x +or +.IR y +is NaN, and the other is not \(+-Inf, a NaN shall be returned. +.P +If both arguments are subnormal and the correct result is subnormal, +a range error may occur and the correct result shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +See the EXAMPLES section in +\fIatan2\fR(). +.SH "APPLICATION USAGE" +\fIhypot\fR(\fIx\fR,\fIy\fR), \fIhypot\fR(\fIy\fR,\fIx\fR), and +\fIhypot\fR(\fIx\fR, \-\fIy\fR) are equivalent. +.P +\fIhypot\fR(\fIx\fR, \(+-0) is equivalent to \fIfabs\fR(\fIx\fR). +.P +Underflow only happens when both +.IR x +and +.IR y +are subnormal and the (inexact) result is also subnormal. +.P +These functions take precautions against overflow during intermediate +steps of the computation. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatan2\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsqrt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iconv.3p b/upstream/archlinux/man3p/iconv.3p new file mode 100644 index 00000000..aeca3e86 --- /dev/null +++ b/upstream/archlinux/man3p/iconv.3p @@ -0,0 +1,237 @@ +'\" et +.TH ICONV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iconv +\(em codeset conversion function +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t iconv(iconv_t \fIcd\fP, char **restrict \fIinbuf\fP, + size_t *restrict \fIinbytesleft\fP, char **restrict \fIoutbuf\fP, + size_t *restrict \fIoutbytesleft\fP); +.fi +.SH DESCRIPTION +The +\fIiconv\fR() +function shall convert the sequence of characters from one codeset, +in the array specified by +.IR inbuf , +into a sequence of corresponding characters in another codeset, in the +array specified by +.IR outbuf . +The codesets are those specified in the +\fIiconv_open\fR() +call that returned the conversion descriptor, +.IR cd . +The +.IR inbuf +argument points to a variable that points to the first character in the +input buffer and +.IR inbytesleft +indicates the number of bytes to the end of the buffer to be +converted. The +.IR outbuf +argument points to a variable that points to the first available byte +in the output buffer and +.IR outbytesleft +indicates the number of the available bytes to the end of the buffer. +.P +For state-dependent encodings, the conversion descriptor +.IR cd +is placed into its initial shift state by a call for which +.IR inbuf +is a null pointer, or for which +.IR inbuf +points to a null pointer. When +\fIiconv\fR() +is called in this way, and if +.IR outbuf +is not a null pointer or a pointer to a null pointer, and +.IR outbytesleft +points to a positive value, +\fIiconv\fR() +shall place, into the output buffer, the byte sequence to change the +output buffer to its initial shift state. If the output buffer is not +large enough to hold the entire reset sequence, +\fIiconv\fR() +shall fail and set +.IR errno +to +.BR [E2BIG] . +Subsequent calls with +.IR inbuf +as other than a null pointer or a pointer to a null pointer cause the +conversion to take place from the current state of the conversion +descriptor. +.P +If a sequence of input bytes does not form a valid character in the +specified codeset, conversion shall stop after the previous +successfully converted character. If the input buffer ends with an +incomplete character or shift sequence, conversion shall stop after the +previous successfully converted bytes. If the output buffer is not +large enough to hold the entire converted input, conversion shall stop +just prior to the input bytes that would cause the output buffer to +overflow. The variable pointed to by +.IR inbuf +shall be updated to point to the byte following the last byte +successfully used in the conversion. The value pointed to by +.IR inbytesleft +shall be decremented to reflect the number of bytes still not converted +in the input buffer. The variable pointed to by +.IR outbuf +shall be updated to point to the byte following the last byte of +converted output data. The value pointed to by +.IR outbytesleft +shall be decremented to reflect the number of bytes still available in +the output buffer. For state-dependent encodings, the conversion +descriptor shall be updated +to reflect the shift state in effect at the end of the last +successfully converted byte sequence. +.P +If +\fIiconv\fR() +encounters a character in the input buffer that is valid, but for which +an identical character does not exist in the target codeset, +\fIiconv\fR() +shall perform an implementation-defined conversion on this character. +.SH "RETURN VALUE" +The +\fIiconv\fR() +function shall update the variables pointed to by the arguments to +reflect the extent of the conversion and return the number of +non-identical conversions performed. If the entire string in the input +buffer is converted, the value pointed to by +.IR inbytesleft +shall be 0. If the input conversion is stopped due to any conditions +mentioned above, the value pointed to by +.IR inbytesleft +shall be non-zero and +.IR errno +shall be set to indicate the condition. If an error occurs, +\fIiconv\fR() +shall return (\fBsize_t\fP)\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIiconv\fR() +function shall fail if: +.TP +.BR EILSEQ +Input conversion stopped due to an input byte that does not belong to +the input codeset. +.TP +.BR E2BIG +Input conversion stopped due to lack of space in the output buffer. +.TP +.BR EINVAL +Input conversion stopped due to an incomplete character or shift +sequence at the end of the input buffer. +.P +The +\fIiconv\fR() +function may fail if: +.TP +.BR EBADF +The +.IR cd +argument is not a valid open conversion descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +.IR inbuf +argument indirectly points to the memory area which contains the +conversion input data. The +.IR outbuf +argument indirectly points to the memory area which is to contain the +result of the conversion. The objects indirectly pointed to by +.IR inbuf +and +.IR outbuf +are not restricted to containing data that is directly representable in +the ISO\ C standard language +.BR char +data type. The type of +.IR inbuf +and +.IR outbuf , +.BR "char **" , +does not imply that the objects pointed to are interpreted as +null-terminated C strings or arrays of characters. Any interpretation +of a byte sequence that represents a character in a given character set +encoding scheme is done internally within the codeset converters. For +example, the area pointed to indirectly by +.IR inbuf +and/or +.IR outbuf +can contain all zero octets that are not interpreted as string +terminators but as coded character data according to the respective +codeset encoding scheme. The type of the data (\c +.BR char , +.BR short , +.BR long , +and so on) read or stored in the objects is not specified, but may be +inferred for both the input and output data by the converters +determined by the +.IR fromcode +and +.IR tocode +arguments of +\fIiconv_open\fR(). +.P +Regardless of the data type inferred by the converter, the size of the +remaining space in both input and output objects (the +.IR intbytesleft +and +.IR outbytesleft +arguments) is always measured in bytes. +.P +For implementations that support the conversion of state-dependent +encodings, the conversion descriptor must be able to accurately reflect +the shift-state in effect at the end of the last successful +conversion. It is not required that the conversion descriptor itself +be updated, which would require it to be a pointer type. Thus, +implementations are free to implement the descriptor as a handle (other +than a pointer type) by which the conversion information can be +accessed and updated. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv_open\fR\^(\|)", +.IR "\fIiconv_close\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iconv_close.3p b/upstream/archlinux/man3p/iconv_close.3p new file mode 100644 index 00000000..bf2b6eaa --- /dev/null +++ b/upstream/archlinux/man3p/iconv_close.3p @@ -0,0 +1,76 @@ +'\" et +.TH ICONV_CLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iconv_close +\(em codeset conversion deallocation function +.SH SYNOPSIS +.LP +.nf +#include +.P +int iconv_close(iconv_t \fIcd\fP); +.fi +.SH DESCRIPTION +The +\fIiconv_close\fR() +function shall deallocate the conversion descriptor +.IR cd +and all other associated resources allocated by +\fIiconv_open\fR(). +.P +If a file descriptor is used to implement the type +.BR iconv_t , +that file descriptor shall be closed. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \-1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIiconv_close\fR() +function may fail if: +.TP +.BR EBADF +The conversion descriptor is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^(\|)", +.IR "\fIiconv_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iconv_open.3p b/upstream/archlinux/man3p/iconv_open.3p new file mode 100644 index 00000000..f42794be --- /dev/null +++ b/upstream/archlinux/man3p/iconv_open.3p @@ -0,0 +1,126 @@ +'\" et +.TH ICONV_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iconv_open +\(em codeset conversion allocation function +.SH SYNOPSIS +.LP +.nf +#include +.P +iconv_t iconv_open(const char *\fItocode\fP, const char *\fIfromcode\fP); +.fi +.SH DESCRIPTION +The +\fIiconv_open\fR() +function shall return a conversion descriptor +that describes a conversion from the codeset specified by the string +pointed to by the +.IR fromcode +argument to the codeset specified by the string pointed to by the +.IR tocode +argument. For state-dependent encodings, the conversion descriptor +shall be in a codeset-dependent initial shift state, ready for +immediate use with +\fIiconv\fR(). +.P +Settings of +.IR fromcode +and +.IR tocode +and their permitted combinations are implementation-defined. +.P +A conversion descriptor shall remain valid until it is closed by +\fIiconv_close\fR() +or an implicit close. +.P +If a file descriptor is used to implement conversion descriptors, the +FD_CLOEXEC flag shall be set; see +.IR . +.SH "RETURN VALUE" +Upon successful completion, +\fIiconv_open\fR() +shall return a conversion descriptor for use on subsequent calls to +\fIiconv\fR(). +Otherwise, +\fIiconv_open\fR() +shall return (\fBiconv_t\fP)\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIiconv_open\fR() +function may fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +Too many files are currently open in the system. +.TP +.BR ENOMEM +Insufficient storage space is available. +.TP +.BR EINVAL +The conversion specified by +.IR fromcode +and +.IR tocode +is not supported by the implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Some implementations of +\fIiconv_open\fR() +use +\fImalloc\fR() +to allocate space for internal buffer areas. The +\fIiconv_open\fR() +function may fail if there is insufficient storage space to accommodate +these buffers. +.P +Conforming applications must assume that conversion descriptors are not +valid after a call to one of the +.IR exec +functions. +.P +Application developers should consult the system documentation to +determine the supported codesets and their naming schemes. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^(\|)", +.IR "\fIiconv_close\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/if_freenameindex.3p b/upstream/archlinux/man3p/if_freenameindex.3p new file mode 100644 index 00000000..8e33efce --- /dev/null +++ b/upstream/archlinux/man3p/if_freenameindex.3p @@ -0,0 +1,74 @@ +'\" et +.TH IF_FREENAMEINDEX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +if_freenameindex +\(em free memory allocated by if_nameindex +.SH SYNOPSIS +.LP +.nf +#include +.P +void if_freenameindex(struct if_nameindex *\fIptr\fP); +.fi +.SH DESCRIPTION +The +\fIif_freenameindex\fR() +function shall free the memory allocated by +\fIif_nameindex\fR(). +The +.IR ptr +argument shall be a pointer that was returned by +\fIif_nameindex\fR(). +After +\fIif_freenameindex\fR() +has been called, the application shall not use the array of which +.IR ptr +is the address. +.SH "RETURN VALUE" +None. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/if_indextoname.3p b/upstream/archlinux/man3p/if_indextoname.3p new file mode 100644 index 00000000..f932ac66 --- /dev/null +++ b/upstream/archlinux/man3p/if_indextoname.3p @@ -0,0 +1,84 @@ +'\" et +.TH IF_INDEXTONAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +if_indextoname +\(em map a network interface index to its corresponding name +.SH SYNOPSIS +.LP +.nf +#include +.P +char *if_indextoname(unsigned \fIifindex\fP, char *\fIifname\fP); +.fi +.SH DESCRIPTION +The +\fIif_indextoname\fR() +function shall map an interface index to its corresponding name. +.P +When this function is called, +.IR ifname +shall point to a buffer of at least +{IF_NAMESIZE} +bytes. The function shall place in this buffer the name of the interface +with index +.IR ifindex . +.SH "RETURN VALUE" +If +.IR ifindex +is an interface index, then the function shall return the value supplied in +.IR ifname , +which points to a buffer now containing the interface name. Otherwise, +the function shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIif_indextoname\fR() +function shall fail if: +.TP +.BR ENXIO +The interface does not exist. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/if_nameindex.3p b/upstream/archlinux/man3p/if_nameindex.3p new file mode 100644 index 00000000..1f763eb0 --- /dev/null +++ b/upstream/archlinux/man3p/if_nameindex.3p @@ -0,0 +1,84 @@ +'\" et +.TH IF_NAMEINDEX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +if_nameindex +\(em return all network interface names and indexes +.SH SYNOPSIS +.LP +.nf +#include +.P +struct if_nameindex *\fIif_nameindex\fP(void); +.fi +.SH DESCRIPTION +The +\fIif_nameindex\fR() +function shall return an array of +.IR if_nameindex +structures, one structure per interface. The end of the array is +indicated by a structure with an +.IR if_index +field of zero and an +.IR if_name +field of NULL. +.P +Applications should call +\fIif_freenameindex\fR() +to release the memory that may be dynamically allocated by this +function, after they have finished using it. +.SH "RETURN VALUE" +An array of structures identifying local interfaces. A null pointer is +returned upon an error, with +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIif_nameindex\fR() +function may fail if: +.TP +.BR ENOBUFS +Insufficient resources are available to complete the function. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nametoindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/if_nametoindex.3p b/upstream/archlinux/man3p/if_nametoindex.3p new file mode 100644 index 00000000..0167d6db --- /dev/null +++ b/upstream/archlinux/man3p/if_nametoindex.3p @@ -0,0 +1,67 @@ +'\" et +.TH IF_NAMETOINDEX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +if_nametoindex +\(em map a network interface name to its corresponding index +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned if_nametoindex(const char *\fIifname\fP); +.fi +.SH DESCRIPTION +The +\fIif_nametoindex\fR() +function shall return the interface index corresponding to name +.IR ifname . +.SH "RETURN VALUE" +The corresponding index if +.IR ifname +is the name of an interface; otherwise, zero. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIif_freenameindex\fR\^(\|)", +.IR "\fIif_indextoname\fR\^(\|)", +.IR "\fIif_nameindex\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ilogb.3p b/upstream/archlinux/man3p/ilogb.3p new file mode 100644 index 00000000..fe2169f9 --- /dev/null +++ b/upstream/archlinux/man3p/ilogb.3p @@ -0,0 +1,195 @@ +'\" et +.TH ILOGB "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.EQ +delim $$ +.EN +.SH NAME +ilogb, +ilogbf, +ilogbl +\(em return an unbiased exponent +.SH SYNOPSIS +.LP +.nf +#include +.P +int ilogb(double \fIx\fP); +int ilogbf(float \fIx\fP); +int ilogbl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall return the exponent part of their argument +.IR x . +Formally, the return value is the integral part of $log sub{r}|x|$ as a +signed integral value, for non-zero +.IR x , +where +.IR r +is the radix of the machine's floating-point arithmetic, which is the +value of FLT_RADIX defined in +.IR . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the exponent +part of +.IR x +as a signed integer value. They are equivalent to calling the +corresponding +\fIlogb\fR() +function and casting the returned value to type +.BR int . +.P +If +.IR x +is 0, the value FP_ILOGB0 shall be returned. +On XSI-conformant systems, a domain error shall occur; +.br +otherwise, a +domain +error may occur. +.P +If +.IR x +is \(+-Inf, the value +{INT_MAX} +shall be returned. +On XSI-conformant systems, a domain error shall occur; +.br +otherwise, a +domain +error may occur. +.P +If +.IR x +is a NaN, the value FP_ILOGBNAN shall be returned. +On XSI-conformant systems, a domain error shall occur; +.br +otherwise, a +domain +error may occur. +.P +If the correct value is greater than +{INT_MAX}, +a domain error shall occur and +an unspecified value shall be returned. +On XSI-conformant systems, a domain error shall occur and +{INT_MAX} +shall be returned. +.P +If the correct value is less than +{INT_MIN}, +a domain error shall occur and +an unspecified value shall be returned. +On XSI-conformant systems, a domain error shall occur and +{INT_MIN} +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +The +.IR x +argument is zero, NaN, or \(+-Inf. +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is zero, NaN, or \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +The errors come from taking the expected floating-point value and +converting it to +.BR int , +which is an invalid operation in IEEE\ Std\ 754\(hy1985 (since overflow, infinity, and +NaN are not representable in a type +.BR int ), +so should be a domain error. +.P +There are no known implementations that overflow. For overflow to +happen, +{INT_MAX} +must be less than LDBL_MAX_EXP*\fIlog2\fP(FLT_RADIX) or +{INT_MIN} +must be greater than LDBL_MIN_EXP*\fIlog2\fP(FLT_RADIX) if subnormals +are not supported, or +{INT_MIN} +must be greater than (LDBL_MIN_EXP-LDBL_MANT_DIG)*\fIlog2\fP(FLT_RADIX) +if subnormals are supported. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlogb\fR\^(\|)", +.IR "\fIscalbln\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/imaxabs.3p b/upstream/archlinux/man3p/imaxabs.3p new file mode 100644 index 00000000..94c8d260 --- /dev/null +++ b/upstream/archlinux/man3p/imaxabs.3p @@ -0,0 +1,69 @@ +'\" et +.TH IMAXABS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +imaxabs +\(em return absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +intmax_t imaxabs(intmax_t \fIj\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIimaxabs\fR() +function shall compute the absolute value of an integer +.IR j . +If the result cannot be represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIimaxabs\fR() +function shall return the absolute value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The absolute value of the most negative number cannot be represented in +two's complement. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIimaxdiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/imaxdiv.3p b/upstream/archlinux/man3p/imaxdiv.3p new file mode 100644 index 00000000..7c035915 --- /dev/null +++ b/upstream/archlinux/man3p/imaxdiv.3p @@ -0,0 +1,78 @@ +'\" et +.TH IMAXDIV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +imaxdiv +\(em return quotient and remainder +.SH SYNOPSIS +.LP +.nf +#include +.P +imaxdiv_t imaxdiv(intmax_t \fInumer\fP, intmax_t \fIdenom\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIimaxdiv\fR() +function shall compute \fInumer\fR\ /\ \fIdenom\fR and +\fInumer\fR\ %\ \fIdenom\fR in a single operation. +.SH "RETURN VALUE" +The +\fIimaxdiv\fR() +function shall return a structure of type +.BR imaxdiv_t , +comprising both the quotient and the remainder. The structure shall +contain (in either order) the members +.IR quot +(the quotient) and +.IR rem +(the remainder), each of which has type +.BR intmax_t . +.P +If either part of the result cannot be represented, the behavior is +undefined. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIimaxabs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/inet_addr.3p b/upstream/archlinux/man3p/inet_addr.3p new file mode 100644 index 00000000..6bc8bc44 --- /dev/null +++ b/upstream/archlinux/man3p/inet_addr.3p @@ -0,0 +1,118 @@ +'\" et +.TH INET_ADDR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +inet_addr, +inet_ntoa +\(em IPv4 address manipulation +.SH SYNOPSIS +.LP +.nf +#include +.P +in_addr_t inet_addr(const char *\fIcp\fP); +char *inet_ntoa(struct in_addr \fIin\fP); +.fi +.SH DESCRIPTION +The +\fIinet_addr\fR() +function shall convert the string pointed to by +.IR cp , +in the standard IPv4 dotted decimal notation, to an integer value +suitable for use as an Internet address. +.P +The +\fIinet_ntoa\fR() +function shall convert the Internet host address specified by +.IR in +to a string in the Internet standard dot notation. +.P +The +\fIinet_ntoa\fR() +function need not be thread-safe. +.P +All Internet addresses shall be returned in network order (bytes +ordered from left to right). +.P +Values specified using IPv4 dotted decimal notation take one of the +following forms: +.IP "\fRa.b.c.d\fP" 10 +When four parts are specified, each shall be interpreted as a byte of +data and assigned, from left to right, to the four bytes of an Internet +address. +.IP "\fRa.b.c\fP" 10 +When a three-part address is specified, the last part shall be +interpreted as a 16-bit quantity and placed in the rightmost two bytes +of the network address. This makes the three-part address format +convenient for specifying Class B network addresses as +.BR \(dq128.net.host\(dq . +.IP "\fRa.b\fP" 10 +When a two-part address is supplied, the last part shall be interpreted +as a 24-bit quantity and placed in the rightmost three bytes of the +network address. This makes the two-part address format convenient for +specifying Class A network addresses as +.BR \(dqnet.host\(dq . +.IP "\fRa\fP" 10 +When only one part is given, the value shall be stored directly in the +network address without any byte rearrangement. +.P +All numbers supplied as parts in IPv4 dotted decimal notation may be +decimal, octal, or hexadecimal, as specified in the ISO\ C standard (that is, a +leading 0x or 0X implies hexadecimal; otherwise, a leading +.BR '0' +implies octal; otherwise, the number is interpreted as decimal). +.SH "RETURN VALUE" +Upon successful completion, +\fIinet_addr\fR() +shall return the Internet address. Otherwise, it shall return (\c +.BR in_addr_t )(\-1). +.P +The +\fIinet_ntoa\fR() +function shall return a pointer to the network address in Internet +standard dot notation. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The return value of +\fIinet_ntoa\fR() +may point to static data that may be overwritten by subsequent calls to +\fIinet_ntoa\fR(). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIendhostent\fR\^(\|)", +.IR "\fIendnetent\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/inet_ntop.3p b/upstream/archlinux/man3p/inet_ntop.3p new file mode 100644 index 00000000..9f62773e --- /dev/null +++ b/upstream/archlinux/man3p/inet_ntop.3p @@ -0,0 +1,202 @@ +'\" et +.TH INET_NTOP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +inet_ntop, +inet_pton +\(em convert IPv4 and IPv6 addresses between binary and text form +.SH SYNOPSIS +.LP +.nf +#include +.P +const char *inet_ntop(int \fIaf\fP, const void *restrict \fIsrc\fP, + char *restrict \fIdst\fP, socklen_t \fIsize\fP); +int inet_pton(int \fIaf\fP, const char *restrict \fIsrc\fP, void *restrict \fIdst\fP); +.fi +.SH DESCRIPTION +The +\fIinet_ntop\fR() +function shall convert a numeric address into a text string suitable +for presentation. The +.IR af +argument shall specify the family of the address. This can be AF_INET +or AF_INET6. +The +.IR src +argument points to a buffer holding an IPv4 address if the +.IR af +argument is AF_INET, +or an IPv6 address if the +.IR af +argument is AF_INET6; +the address must be in network byte order. The +.IR dst +argument points to a buffer where the function stores the resulting +text string; it shall not be NULL. The +.IR size +argument specifies the size of this buffer, which shall be large enough +to hold the text string (INET_ADDRSTRLEN characters for IPv4, +INET6_ADDRSTRLEN characters for IPv6). +.P +The +\fIinet_pton\fR() +function shall convert an address in its standard text presentation +form into its numeric binary form. The +.IR af +argument shall specify the family of the address. The AF_INET +and AF_INET6 +address families shall be supported. The +.IR src +argument points to the string being passed in. The +.IR dst +argument points to a buffer into which the function stores the numeric +address; this shall be large enough to hold the numeric address (32 bits +for AF_INET, +128 bits for AF_INET6). +.P +If the +.IR af +argument of +\fIinet_pton\fR() +is AF_INET, the +.IR src +string shall be in the standard IPv4 dotted-decimal form: +.sp +.RS 4 +.nf + +ddd.ddd.ddd.ddd +.fi +.P +.RE +.P +where +.BR \(dqddd\(dq +is a one to three digit decimal number between 0 and 255 (see +.IR "\fIinet_addr\fR\^(\|)"). +The +\fIinet_pton\fR() +function does not accept other formats (such as the octal numbers, +hexadecimal numbers, and fewer than four numbers that +\fIinet_addr\fR() +accepts). +.P +If the +.IR af +argument of +\fIinet_pton\fR() +is AF_INET6, the +.IR src +string shall be in one of the following standard IPv6 text forms: +.IP " 1." 4 +The preferred form is +.BR \(dqx:x:x:x:x:x:x:x\(dq , +where the +.BR 'x' s +are the hexadecimal values of the eight 16-bit pieces of the address. +Leading zeros in individual fields can be omitted, but there shall be +one to four hexadecimal digits in every field. +.IP " 2." 4 +A string of contiguous zero fields in the preferred form can be shown +as +.BR \(dq::\(dq . +The +.BR \(dq::\(dq +can only appear once in an address. Unspecified addresses (\c +.BR \(dq0:0:0:0:0:0:0:0\(dq ) +may be represented simply as +.BR \(dq::\(dq . +.IP " 3." 4 +A third form that is sometimes more convenient when dealing with a +mixed environment of IPv4 and IPv6 nodes is +.BR \(dqx:x:x:x:x:x:d.d.d.d\(dq , +where the +.BR 'x' s +are the hexadecimal values of the six high-order 16-bit pieces of the +address, and the +.BR 'd' s +are the decimal values of the four low-order 8-bit pieces of the +address (standard IPv4 representation). +.TP 10 +.BR Note: +A more extensive description of the standard representations of IPv6 +addresses can be found in RFC\ 2373. +.P +.SH "RETURN VALUE" +The +\fIinet_ntop\fR() +function shall return a pointer to the buffer containing the text +string if the conversion succeeds, and NULL otherwise, and set +.IR errno +to indicate the error. +.P +The +\fIinet_pton\fR() +function shall return 1 if the conversion succeeds, with the address +pointed to by +.IR dst +in network byte order. It shall return 0 if the input is not a valid +IPv4 dotted-decimal string +or a valid IPv6 address string, +or \-1 with +.IR errno +set to +.BR [EAFNOSUPPORT] +if the +.IR af +argument is unknown. +.SH ERRORS +The +\fIinet_ntop\fR() +and +\fIinet_pton\fR() +functions shall fail if: +.TP +.BR EAFNOSUPPORT +.br +The +.IR af +argument is invalid. +.TP +.BR ENOSPC +The size of the +\fIinet_ntop\fR() +result buffer is inadequate. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/initstate.3p b/upstream/archlinux/man3p/initstate.3p new file mode 100644 index 00000000..dcb3cc09 --- /dev/null +++ b/upstream/archlinux/man3p/initstate.3p @@ -0,0 +1,194 @@ +'\" et +.TH INITSTATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +initstate, +random, +setstate, +srandom +\(em pseudo-random number functions +.SH SYNOPSIS +.LP +.nf +#include +.P +char *initstate(unsigned \fIseed\fP, char *\fIstate\fP, size_t \fIsize\fP); +long random(void); +char *setstate(char *\fIstate\fP); +void srandom(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +The +\fIrandom\fR() +function shall use a non-linear additive feedback random-number +generator employing a default state array size of 31 +.BR long +integers to return successive pseudo-random numbers in the range from 0 +to 2\u\s-331\s+3\d\-1. The period of this random-number generator is +approximately 16 x (2\s-3\u31\d\s+3\-\fR1). The size of the state +array determines the period of the random-number generator. Increasing +the state array size shall increase the period. +.P +With 256 bytes of state information, the period of the random-number +generator shall be greater than 2\s-3\u69\d\s+3. +.P +Like +\fIrand\fR(), +\fIrandom\fR() +shall produce by default a sequence of numbers that can be duplicated +by calling +\fIsrandom\fR() +with 1 as the seed. +.P +The +\fIsrandom\fR() +function shall initialize the current state array using the value of +.IR seed . +.P +The +\fIinitstate\fR() +and +\fIsetstate\fR() +functions handle restarting and changing random-number generators. The +\fIinitstate\fR() +function allows a state array, pointed to by the +.IR state +argument, to be initialized for future use. The +.IR size +argument, which specifies the size in bytes of the state array, shall +be used by +\fIinitstate\fR() +to decide what type of random-number generator to use; the larger the +state array, the more random the numbers. Values for the amount of +state information are 8, 32, 64, 128, and 256 bytes. Other values +greater than 8 bytes are rounded down to the nearest one of these +values. If +\fIinitstate\fR() +is called with 8\(<=\fIsize\fR<32, then +\fIrandom\fR() +shall use a simple linear congruential random number generator. The +.IR seed +argument specifies a starting point for the random-number sequence and +provides for restarting at the same point. The +\fIinitstate\fR() +function shall return a pointer to the previous state information array. +.P +If +\fIinitstate\fR() +has not been called, then +\fIrandom\fR() +shall behave as though +\fIinitstate\fR() +had been called with +.IR seed =1 +and +.IR size =128. +.P +Once a state has been initialized, +\fIsetstate\fR() +allows switching between state arrays. The array defined by the +.IR state +argument shall be used for further random-number generation until +\fIinitstate\fR() +is called or +\fIsetstate\fR() +is called again. The +\fIsetstate\fR() +function shall return a pointer to the previous state array. +.SH "RETURN VALUE" +If +\fIinitstate\fR() +is called with +.IR size +less than 8, it shall return NULL. +.P +The +\fIrandom\fR() +function shall return the generated pseudo-random number. +.P +The +\fIsrandom\fR() +function shall not return a value. +.P +Upon successful completion, +\fIinitstate\fR() +and +\fIsetstate\fR() +shall return a pointer to the previous state array; otherwise, a null +pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After initialization, a state array can be restarted at a different +point in one of two ways: +.IP " 1." 4 +The +\fIinitstate\fR() +function can be used, with the desired seed, state array, and size of +the array. +.IP " 2." 4 +The +\fIsetstate\fR() +function, with the desired state, can be used, followed by +\fIsrandom\fR() +with the desired seed. The advantage of using both of these functions +is that the size of the state array does not have to be saved once it +is initialized. +.P +Although some implementations of +\fIrandom\fR() +have written messages to standard error, such implementations do not +conform to POSIX.1\(hy2008. +.P +Issue 5 restored the historical behavior of this function. +.P +Threaded applications should use +\fIerand48\fR(), +\fInrand48\fR(), +or +\fIjrand48\fR() +instead of +\fIrandom\fR() +when an independent random number sequence in multiple threads is +required. +.P +These functions should be avoided whenever non-trivial requirements +(including safety) have to be fulfilled. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdrand48\fR\^(\|)", +.IR "\fIrand\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/insque.3p b/upstream/archlinux/man3p/insque.3p new file mode 100644 index 00000000..8e03acdd --- /dev/null +++ b/upstream/archlinux/man3p/insque.3p @@ -0,0 +1,216 @@ +'\" et +.TH INSQUE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +insque, +remque +\(em insert or remove an element in a queue +.SH SYNOPSIS +.LP +.nf +#include +.P +void insque(void *\fIelement\fP, void *\fIpred\fP); +void remque(void *\fIelement\fP); +.fi +.SH DESCRIPTION +The +\fIinsque\fR() +and +\fIremque\fR() +functions shall manipulate queues built from doubly-linked lists. +The queue can be either circular or linear. An application using +\fIinsque\fR() +or +\fIremque\fR() +shall ensure it defines a structure in which the first two members of +the structure are pointers to the same type of structure, and any +further members are application-specific. The first member of the +structure is a forward pointer to the next entry in the queue. The +second member is a backward pointer to the previous entry in the queue. +If the queue is linear, the queue is terminated with null pointers. The +names of the structure and of the pointer members are not subject to +any special restriction. +.P +The +\fIinsque\fR() +function shall insert the element pointed to by +.IR element +into a queue immediately after the element pointed to by +.IR pred . +.P +The +\fIremque\fR() +function shall remove the element pointed to by +.IR element +from a queue. +.P +If the queue is to be used as a linear list, invoking +\fIinsque\fP(&\fIelement\fP, NULL), where +.IR element +is the initial element of the queue, shall initialize the forward +and backward pointers of +.IR element +to null pointers. +.P +If the queue is to be used as a circular list, the application shall +ensure it initializes the forward pointer and the backward pointer of +the initial element of the queue to the element's own address. +.SH "RETURN VALUE" +The +\fIinsque\fR() +and +\fIremque\fR() +functions do not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Linear Linked List" +.P +The following example creates a linear linked list. +.sp +.RS 4 +.nf + +#include +\&... +struct myque element1; +struct myque element2; +.P +char *data1 = "DATA1"; +char *data2 = "DATA2"; +\&... +element1.data = data1; +element2.data = data2; +.P +insque (&element1, NULL); +insque (&element2, &element1); +.fi +.P +.RE +.SS "Creating a Circular Linked List" +.P +The following example creates a circular linked list. +.sp +.RS 4 +.nf + +#include +\&... +struct myque element1; +struct myque element2; +.P +char *data1 = "DATA1"; +char *data2 = "DATA2"; +\&... +element1.data = data1; +element2.data = data2; +.P +element1.fwd = &element1; +element1.bck = &element1; +.P +insque (&element2, &element1); +.fi +.P +.RE +.SS "Removing an Element" +.P +The following example removes the element pointed to by +.IR element1 . +.sp +.RS 4 +.nf + +#include +\&... +struct myque element1; +\&... +remque (&element1); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The historical implementations of these functions described the +arguments as being of type +.BR "struct qelem *" +rather than as being of type +.BR "void *" +as defined here. In those implementations, +.BR "struct qelem" +was commonly defined in +.IR +as: +.sp +.RS 4 +.nf + +struct qelem { + struct qelem *q_forw; + struct qelem *q_back; +}; +.fi +.P +.RE +.P +Applications using these functions, however, were never able to use +this structure directly since it provided no room for the actual data +contained in the elements. Most applications defined structures that +contained the two pointers as the initial elements and also provided +space for, or pointers to, the object's data. Applications that used +these functions to update more than one type of table also had the +problem of specifying two or more different structures with the same +name, if they literally used +.BR "struct qelem" +as specified. +.P +As described here, the implementations were actually expecting a +structure type where the first two members were forward and backward +pointers to structures. With C compilers that didn't provide function +prototypes, applications used structures as specified in the +DESCRIPTION above and the compiler did what the application expected. +.P +If this method had been carried forward with an ISO\ C standard compiler and the +historical function prototype, most applications would have to be +modified to cast pointers to the structures actually used to be +pointers to +.BR "struct qelem" +to avoid compilation warnings. By specifying +.BR "void *" +as the argument type, applications do not need to change (unless +they specifically referenced +.BR "struct qelem" +and depended on it being defined in +.IR ). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ioctl.3p b/upstream/archlinux/man3p/ioctl.3p new file mode 100644 index 00000000..aedf5a2f --- /dev/null +++ b/upstream/archlinux/man3p/ioctl.3p @@ -0,0 +1,1216 @@ +'\" et +.TH IOCTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ioctl +\(em control a STREAMS device (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int ioctl(int \fIfildes\fP, int \fIrequest\fP, ... /* arg */); +.fi +.SH DESCRIPTION +The +\fIioctl\fR() +function shall perform a variety of control functions on STREAMS +devices. For non-STREAMS devices, the functions performed by this call +are unspecified. The +.IR request +argument and an optional third argument (with varying type) shall be +passed to and interpreted by the appropriate part of the STREAM +associated with +.IR fildes . +.P +The +.IR fildes +argument is an open file descriptor that refers to a device. +.P +The +.IR request +argument selects the control function to be performed and shall +depend on the STREAMS device being addressed. +.P +The +.IR arg +argument represents additional information that is needed by this +specific STREAMS device to perform the requested function. The type of +.IR arg +depends upon the particular control request, but it shall be either an +integer or a pointer to a device-specific data structure. +.P +The +\fIioctl\fR() +commands applicable to STREAMS, their arguments, and error conditions +that apply to each individual command are described below. +.P +The following +\fIioctl\fR() +commands, with error values indicated, are applicable to all STREAMS +files: +.IP I_PUSH 12 +Pushes the module whose name is pointed to by +.IR arg +onto the top of the current STREAM, just below the STREAM head. It then +calls the +\fIopen\fR() +function of the newly-pushed module. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PUSH command shall fail if: +.TP +.BR EINVAL +Invalid module name. +.TP +.BR ENXIO +Open function of new module failed. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_POP 12 +Removes the module just below the STREAM head of the STREAM pointed to +by +.IR fildes . +The +.IR arg +argument should be 0 in an I_POP request. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_POP command shall fail if: +.TP +.BR EINVAL +No module present in the STREAM. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_LOOK 12 +Retrieves the name of the module just below the STREAM head of the +STREAM pointed to by +.IR fildes , +and places it in a character string pointed to by +.IR arg . +The buffer pointed to by +.IR arg +should be at least FMNAMESZ+1 +bytes long, where FMNAMESZ is defined in +.IR . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_LOOK command shall fail if: +.TP +.BR EINVAL +No module present in the STREAM. +.RE +.IP I_FLUSH 12 +Flushes read and/or write queues, depending on the value of +.IR arg . +Valid +.IR arg +values are: +.RS 12 +.IP FLUSHR 12 +Flush all read queues. +.IP FLUSHW 12 +Flush all write queues. +.IP FLUSHRW 12 +Flush all read and all write queues. +.P +The +\fIioctl\fR() +function with the I_FLUSH command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for flush message. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_FLUSHBAND 12 +Flushes a particular band of messages. The +.IR arg +argument points to a +.BR bandinfo +structure. The +.IR bi_flag +member may be one of FLUSHR, FLUSHW, or FLUSHRW as described above. The +.IR bi_pri +member determines the priority band to be flushed. +.IP I_SETSIG 12 +Requests that the STREAMS implementation send the SIGPOLL signal to the +calling process when a particular event has occurred on +the STREAM associated with +.IR fildes . +I_SETSIG supports an asynchronous processing capability in STREAMS. The +value of +.IR arg +is a bitmask that specifies the events for which the process should be +signaled. It is the bitwise-inclusive OR of any combination of the +following constants: +.RS 12 +.IP S_RDNORM 12 +A normal (priority band set to 0) message has arrived at the head of a +STREAM head read queue. A signal shall be generated even if the message +is of zero length. +.IP S_RDBAND 12 +A message with a non-zero priority band has arrived at the head of a +STREAM head read queue. A signal shall be generated even if the message +is of zero length. +.IP S_INPUT 12 +A message, other than a high-priority message, has arrived at the head +of a STREAM head read queue. A signal shall be generated even if the +message is of zero length. +.IP S_HIPRI 12 +A high-priority message is present on a STREAM head read queue. A +signal shall be generated even if the message is of zero length. +.IP S_OUTPUT 12 +The write queue for normal data (priority band 0) just below the STREAM +head is no longer full. This notifies the process that there is room +on the queue for sending (or writing) normal data downstream. +.IP S_WRNORM 12 +Equivalent to S_OUTPUT. +.IP S_WRBAND 12 +The write queue for a non-zero priority band just below the STREAM head +is no longer full. This notifies the process that there is room on the +queue for sending (or writing) priority data downstream. +.IP S_MSG 12 +A STREAMS signal message that contains the SIGPOLL signal has reached +the front of the STREAM head read queue. +.IP S_ERROR 12 +Notification of an error condition has reached the STREAM head. +.IP S_HANGUP 12 +Notification of a hangup has reached the STREAM head. +.IP S_BANDURG 12 +When used in conjunction with S_RDBAND, SIGURG is generated instead of +SIGPOLL when a priority message reaches the front of the STREAM head +read queue. +.P +If +.IR arg +is 0, the calling process shall be unregistered and shall not receive +further SIGPOLL signals for the stream associated with +.IR fildes . +.P +Processes that wish to receive SIGPOLL signals shall ensure that they +explicitly register to receive them using I_SETSIG. If several +processes register to receive this +signal for the same event on the same STREAM, each process shall be +signaled when the event occurs. +.P +The +\fIioctl\fR() +function with the I_SETSIG command shall fail if: +.TP +.BR EINVAL +The value of +.IR arg +is invalid. +.TP +.BR EINVAL +The value of +.IR arg +is 0 and the calling process is not registered to receive +the SIGPOLL signal. +.TP +.BR EAGAIN +There were insufficient resources to store the signal request. +.RE +.IP I_GETSIG 12 +Returns the events for which the calling process is currently +registered to be sent a SIGPOLL signal. The events are returned as a +bitmask in an +.BR int +pointed to by +.IR arg , +where the events are those specified in the description of +I_SETSIG above. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_GETSIG command shall fail if: +.TP +.BR EINVAL +Process is not registered to receive the SIGPOLL signal. +.RE +.IP I_FIND 12 +Compares the names of all modules currently present in the STREAM to +the name pointed to by +.IR arg , +and returns 1 if the named module is present in the STREAM, or returns +0 if the named module is not present. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_FIND command shall fail if: +.TP +.BR EINVAL +.IR arg +does not contain a valid module name. +.RE +.IP I_PEEK 12 +Retrieves the information in the first message on the STREAM head read +queue without taking the message off the queue. It is analogous to +\fIgetmsg\fR() +except that this command does not remove the message from the queue. +The +.IR arg +argument points to a +.BR strpeek +structure. +.RS 12 +.P +The application shall ensure that the +.IR maxlen +member in the +.BR ctlbuf +and +.BR "databuf strbuf" +structures is set to the number of bytes of control information and/or +data information, respectively, to retrieve. The +.IR flags +member may be marked RS_HIPRI or 0, as described by +\fIgetmsg\fR(). +If the process sets +.IR flags +to RS_HIPRI, for example, I_PEEK shall only look for a high-priority +message on the STREAM head read queue. +.P +I_PEEK returns 1 if a message was retrieved, and returns 0 if no +message was found on the STREAM head read queue, or if the RS_HIPRI +flag was set in +.IR flags +and a high-priority message was not present on the STREAM head read +queue. It does not wait for a message to arrive. On return, +.BR ctlbuf +specifies information in the control buffer, +.BR databuf +specifies information in the data buffer, and +.IR flags +contains the value RS_HIPRI or 0. +.RE +.IP I_SRDOPT 12 +Sets the read mode using the value of the argument +.IR arg . +Read modes are described in +\fIread\fR(). +Valid +.IR arg +flags are: +.RS 12 +.IP RNORM 12 +Byte-stream mode, the default. +.IP RMSGD 12 +Message-discard mode. +.IP RMSGN 12 +Message-nondiscard mode. +.P +The bitwise-inclusive OR of RMSGD and RMSGN shall return +.BR [EINVAL] . +The bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall +result in the other flag overriding RNORM which is the default. +.P +In addition, treatment of control messages by the STREAM head may be +changed by setting any of the following flags in +.IR arg : +.IP RPROTNORM 12 +Fail +\fIread\fR() +with +.BR [EBADMSG] +if a message containing a control part is at the front of the +STREAM head read queue. +.IP RPROTDAT 12 +Deliver the control part of a message as data when a process issues a +\fIread\fR(). +.IP RPROTDIS 12 +Discard the control part of a message, delivering any data portion, +when a process issues a +\fIread\fR(). +.P +The +\fIioctl\fR() +function with the I_SRDOPT command shall fail if: +.TP +.BR EINVAL +The +.IR arg +argument is not valid. +.RE +.IP I_GRDOPT 12 +Returns the current read mode setting, as described above, in an +.BR int +pointed to by the argument +.IR arg . +Read modes are described in +\fIread\fR(). +.IP I_NREAD 12 +Counts the number of data bytes in the data part of the first message +on the STREAM head read queue and places this value in the +.BR int +pointed to by +.IR arg . +The return value for the command shall be the number of messages on the +STREAM head read queue. For example, if 0 is returned in +.IR arg , +but the +\fIioctl\fR() +return value is greater than 0, this indicates that a zero-length +message is next on the queue. +.IP I_FDINSERT 12 +Creates a message from specified buffer(s), adds information about +another STREAM, and sends the message downstream. The message contains +a control part and an optional data part. The data and control parts to +be sent are distinguished by placement in separate buffers, as +described below. The +.IR arg +argument points to a +.BR strfdinsert +structure. +.RS 12 +.P +The application shall ensure that the +.IR len +member in the +.BR "ctlbuf strbuf" +structure is set to the size of a +.BR t_uscalar_t +plus the number of bytes of control information to be sent with the +message. The +.IR fildes +member specifies the file descriptor of the other STREAM, and the +.IR offset +member, which must be suitably aligned for use as a +.BR t_uscalar_t , +specifies the offset from the start of the control buffer where +I_FDINSERT shall store a +.BR t_uscalar_t +whose interpretation is specific to the STREAM end. The application +shall ensure that the +.IR len +member in the +.BR "databuf strbuf" +structure is set to the number of bytes of data information to be sent +with the message, or to 0 if no data part is to be sent. +.P +The +.IR flags +member specifies the type of message to be created. A normal message is +created if +.IR flags +is set to 0, and a high-priority message is created if +.IR flags +is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if +the STREAM write queue is full due to internal flow control conditions. +For priority messages, I_FDINSERT does not block on this condition. For +non-priority messages, I_FDINSERT does not block when the write queue +is full and O_NONBLOCK is set. Instead, it fails and sets +.IR errno +to +.BR [EAGAIN] . +.P +I_FDINSERT also blocks, unless prevented by lack of internal resources, +waiting for the availability of message blocks in the STREAM, +regardless of priority or whether O_NONBLOCK has been specified. No +partial message is sent. +.P +The +\fIioctl\fR() +function with the I_FDINSERT command shall fail if: +.TP +.BR EAGAIN +A non-priority message is specified, the O_NONBLOCK flag is set, and +the STREAM write queue is full due to internal flow control +conditions. +.TP +.BR EAGAIN " or " ENOSR +.br +Buffers cannot be allocated for the message that is to be created. +.TP +.BR EINVAL +One of the following: +.RS 12 +.IP -- 4 +The +.IR fildes +member of the +.BR strfdinsert +structure is not a valid, open STREAM file descriptor. +.IP -- 4 +The size of a +.BR t_uscalar_t +plus +.IR offset +is greater than the +.IR len +member for the buffer specified through +.BR ctlbuf . +.IP -- 4 +The +.IR offset +member does not specify a properly-aligned location in the data buffer. +.IP -- 4 +An undefined value is stored in +.IR flags . +.RE +.TP +.BR ENXIO +Hangup received on the STREAM identified by either the +.IR fildes +argument or the +.IR fildes +member of the +.BR strfdinsert +structure. +.TP +.BR ERANGE +The +.IR len +member for the buffer specified through +.BR databuf +does not fall within the range specified by the maximum and minimum +packet sizes of the topmost STREAM module; or the +.IR len +member for the buffer specified through +.BR databuf +is larger than the maximum configured size of the data part of a +message; or the +.IR len +member for the buffer specified through +.BR ctlbuf +is larger than the maximum configured size of the control part of a +message. +.RE +.IP I_STR 12 +Constructs an internal STREAMS +\fIioctl\fR() +message from the data pointed to by +.IR arg , +and sends that message downstream. +.RS 12 +.P +This mechanism is provided to send +\fIioctl\fR() +requests to downstream modules and drivers. It allows information to be +sent with +\fIioctl\fR(), +and returns to the process any information sent upstream by the +downstream recipient. I_STR shall block until the system responds with +either a positive or negative acknowledgement message, or until the +request times out after some period of time. If the request times out, +it shall fail with +.IR errno +set to +.BR [ETIME] . +.P +At most, one I_STR can be active on a STREAM. Further I_STR calls shall +block until the active I_STR completes at the STREAM head. The default +timeout interval for these requests is 15 seconds. The O_NONBLOCK flag +has no effect on this call. +.P +To send requests downstream, the application shall ensure that +.IR arg +points to a +.BR strioctl +structure. +.P +The +.IR ic_cmd +member is the internal +\fIioctl\fR() +command intended for a downstream module or driver and +.IR ic_timout +is the number of seconds (\-1=infinite, 0=use +implementation-defined timeout interval, >0=as specified) an I_STR +request shall wait for acknowledgement before timing out. +.IR ic_len +is the number of bytes in the data argument, and +.IR ic_dp +is a pointer to the data argument. The +.IR ic_len +member has two uses: on input, it contains the length of the data +argument passed in, and on return from the command, it contains the +number of bytes being returned to the process (the buffer pointed to by +.IR ic_dp +should be large enough to contain the maximum amount of data that any +module or the driver in the STREAM can return). +.P +The STREAM head shall convert the information pointed to by the +.BR strioctl +structure to an internal +\fIioctl\fR() +command message and send it downstream. +.P +The +\fIioctl\fR() +function with the I_STR command shall fail if: +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the +\fIioctl\fR() +message. +.TP +.BR EINVAL +The +.IR ic_len +member is less than 0 or larger than the maximum configured size of the +data part of a message, or +.IR ic_timout +is less than \-1. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +A downstream +\fIioctl\fR() +timed out before acknowledgement was received. +.P +An I_STR can also fail while waiting for an acknowledgement if a +message indicating an error or a hangup is received at the STREAM head. +In addition, an error code can be returned in the positive or negative +acknowledgement message, in the event the +\fIioctl\fR() +command sent downstream fails. For these cases, I_STR shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_SWROPT 12 +Sets the write mode using the value of the argument +.IR arg . +Valid bit settings for +.IR arg +are: +.RS 12 +.IP SNDZERO 12 +Send a zero-length message downstream when a +\fIwrite\fR() +of 0 bytes occurs. To not send a zero-length message when a +\fIwrite\fR() +of 0 bytes occurs, the application shall ensure that this bit is not +set in +.IR arg +(for example, +.IR arg +would be set to 0). +.P +The +\fIioctl\fR() +function with the I_SWROPT command shall fail if: +.TP +.BR EINVAL +.IR arg +is not the above value. +.RE +.IP I_GWROPT 12 +Returns the current write mode setting, as described above, in the +.BR int +that is pointed to by the argument +.IR arg . +.IP I_SENDFD 12 +Creates a new reference to the open file description associated with +the file descriptor +.IR arg , +and writes a message on the STREAMS-based pipe +.IR fildes +containing this reference, together with the user ID and group ID of +the calling process. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_SENDFD command shall fail if: +.TP +.BR EAGAIN +The sending STREAM is unable to allocate a message block to contain the +file pointer; or the read queue of the receiving STREAM head is full +and cannot accept the message sent by I_SENDFD. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument is not connected to a STREAM pipe. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.P +The +\fIioctl\fR() +function with the I_SENDFD command may fail if: +.TP +.BR EINVAL +The +.IR arg +argument is equal to the +.IR fildes +argument. +.RE +.IP I_RECVFD 12 +Retrieves the reference to an open file description from a message +written to a STREAMS-based pipe using the I_SENDFD command, and +allocates a new file descriptor in the calling process that refers to +this open file description. The +.IR arg +argument is a pointer to a +.BR strrecvfd +data structure as defined in +.IR . +.RS 12 +.P +The +.IR fd +member is a file descriptor. The +.IR uid +and +.IR gid +members are the effective user ID and effective group ID, respectively, +of the sending process. +.P +If O_NONBLOCK is not set, I_RECVFD shall block until a message is +present at the STREAM head. If O_NONBLOCK is set, I_RECVFD shall fail +with +.IR errno +set to +.BR [EAGAIN] +if no message is present at the STREAM head. +.P +If the message at the STREAM head is a message sent by an I_SENDFD, a +new file +descriptor shall be allocated for the open file descriptor referenced +in the message. The new file descriptor is placed in the +.IR fd +member of the +.BR strrecvfd +structure pointed to by +.IR arg . +.P +The +\fIioctl\fR() +function with the I_RECVFD command shall fail if: +.TP +.BR EAGAIN +A message is not present at the STREAM head read queue and the +O_NONBLOCK flag is set. +.TP +.BR EBADMSG +The message at the STREAM head read queue is not a message containing a +passed file descriptor. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.RE +.IP I_LIST 12 +Allows the process to list all the module names on the STREAM, up to +and including the topmost driver name. If +.IR arg +is a null pointer, the return value shall be the number of modules, +including the driver, that are on the STREAM pointed to by +.IR fildes . +This lets the process allocate enough space for the module names. +Otherwise, it should point to a +.BR str_list +structure. +.RS 12 +.P +The +.IR sl_nmods +member indicates the number of entries the process has allocated in the +array. Upon return, the +.IR sl_modlist +member of the +.BR str_list +structure shall contain the list of module names, and the number of +entries that have been filled into the +.IR sl_modlist +array is found in the +.IR sl_nmods +member (the number includes the number of modules including the +driver). The return value from +\fIioctl\fR() +shall be 0. The entries are filled in starting at the top of the STREAM +and continuing downstream until either the end of the STREAM is +reached, or the number of requested modules (\c +.IR sl_nmods ) +is satisfied. +.P +The +\fIioctl\fR() +function with the I_LIST command shall fail if: +.TP +.BR EINVAL +The +.IR sl_nmods +member is less than 1. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers. +.RE +.IP I_ATMARK 12 +Allows the process to see if the message at the head of the STREAM head +read queue is marked by some module downstream. The +.IR arg +argument determines how the checking is done when there may be multiple +marked messages on the STREAM head read queue. It may take on the +following values: +.RS 12 +.IP ANYMARK 12 +Check if the message is marked. +.IP LASTMARK 12 +Check if the message is the last one marked on the queue. +.P +The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted. +.P +The return value shall be 1 if the mark condition is satisfied; +otherwise, the value shall be 0. +.P +The +\fIioctl\fR() +function with the I_ATMARK command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_CKBAND 12 +Checks if the message of a given priority band exists on the STREAM +head read queue. This shall return 1 if a message of the given priority +exists, 0 if no such message exists, or \-1 on error. +.IR arg +should be of type +.BR int . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_CKBAND command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_GETBAND 12 +Returns the priority band of the first message on the STREAM head read +queue in the integer referenced by +.IR arg . +.RS 12 +.P +The +\fIioctl\fR() +function with the I_GETBAND command shall fail if: +.TP +.BR ENODATA +No message on the STREAM head read queue. +.RE +.IP I_CANPUT 12 +Checks if a certain band is writable. +.IR arg +is set to the priority band in question. The return value shall be 0 if +the band is flow-controlled, 1 if the band is writable, or \-1 on +error. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_CANPUT command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_SETCLTIME 12 +This request allows the process to set the time the STREAM head shall +delay when a STREAM is closing and there is data on the write queues. +Before closing each module or driver, if there is data on its write +queue, the STREAM head shall delay for the specified amount of time to +allow the data to drain. If, after the delay, data is still present, it +shall be flushed. The +.IR arg +argument is a pointer to an integer specifying the number of +milliseconds to delay, rounded up to the nearest valid value. If +I_SETCLTIME is not performed on a STREAM, an implementation-defined +default timeout interval is used. +.br +.RS 12 +.P +The +\fIioctl\fR() +function with the I_SETCLTIME command shall fail if: +.TP +.BR EINVAL +Invalid +.IR arg +value. +.RE +.IP I_GETCLTIME 12 +Returns the close time delay in the integer pointed to by +.IR arg . +.SS "Multiplexed STREAMS Configurations" +.P +The following commands are used for connecting and disconnecting +multiplexed STREAMS configurations. These commands use an +implementation-defined default timeout interval. +.IP I_LINK 12 +Connects two STREAMs, where +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver, and +.IR arg +is the file descriptor of the STREAM connected to another driver. The +STREAM designated by +.IR arg +is connected below the multiplexing driver. I_LINK requires the +multiplexing driver to send an acknowledgement message to the STREAM +head regarding the connection. This call shall return a multiplexer ID +number (an identifier used to disconnect the multiplexer; see I_UNLINK) +on success, and \-1 on failure. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_LINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate STREAMS storage to perform the I_LINK. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument does not support multiplexing; or +.IR arg +is not a STREAM or is already connected downstream from a multiplexer; +or the specified I_LINK operation would connect the STREAM head in more +than one place in the multiplexed STREAM. +.P +An I_LINK can also fail while waiting for the multiplexing driver to +acknowledge the request, if a message indicating an error or a hangup +is received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_LINK fails with +.IR errno +set to the value in the message. +.RE +.IP I_UNLINK 12 +Disconnects the two STREAMs specified by +.IR fildes +and +.IR arg . +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver. The +.IR arg +argument is the multiplexer ID number that was returned by the I_LINK +\fIioctl\fR() +command when a STREAM was connected downstream from the multiplexing +driver. If +.IR arg +is MUXID_ALL, then all STREAMs that were connected to +.IR fildes +shall be disconnected. As in I_LINK, this command requires +acknowledgement. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_UNLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the acknowledgement message. +.TP +.BR EINVAL +Invalid multiplexer ID number. +.P +An I_UNLINK can also fail while waiting for the multiplexing driver to +acknowledge the request if a message indicating an error or a hangup is +received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_UNLINK shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_PLINK 12 +Creates a +.IR "persistent connection" +between two STREAMs, where +.IR fildes +is the file descriptor of the STREAM connected to the multiplexing +driver, and +.IR arg +is the file descriptor of the STREAM connected to another driver. This +call shall create a persistent connection which can exist even if the +file descriptor +.IR fildes +associated with the upper STREAM to the multiplexing driver is closed. +The STREAM designated by +.IR arg +gets connected via a persistent connection below the multiplexing +driver. I_PLINK requires the multiplexing driver to send an +acknowledgement message to the STREAM head. This call shall return a +multiplexer ID number (an identifier that may be used to disconnect the +multiplexer; see I_PUNLINK) on success, and \-1 on failure. +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate STREAMS storage to perform the I_PLINK. +.TP +.BR EBADF +The +.IR arg +argument is not a valid, open file descriptor. +.TP +.BR EINVAL +The +.IR fildes +argument does not support multiplexing; or +.IR arg +is not a STREAM or is already connected downstream from a multiplexer; +or the specified I_PLINK operation would connect the STREAM head in +more than one place in the multiplexed STREAM. +.P +An I_PLINK can also fail while waiting for the multiplexing driver to +acknowledge the request, if a message indicating an error or a hangup +is received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PLINK shall fail with +.IR errno +set to the value in the message. +.RE +.IP I_PUNLINK 12 +Disconnects the two STREAMs specified by +.IR fildes +and +.IR arg +from a persistent connection. The +.IR fildes +argument is the file descriptor of the STREAM connected to the +multiplexing driver. The +.IR arg +argument is the multiplexer ID number that was returned by the I_PLINK +\fIioctl\fR() +command when a STREAM was connected downstream from the multiplexing +driver. If +.IR arg +is MUXID_ALL, then all STREAMs which are persistent connections +to +.IR fildes +shall be disconnected. As in I_PLINK, this command requires the +multiplexing driver to acknowledge the request. +.br +.RS 12 +.P +The +\fIioctl\fR() +function with the I_PUNLINK command shall fail if: +.TP +.BR ENXIO +Hangup received on +.IR fildes . +.TP +.BR ETIME +Timeout before acknowledgement message was received at STREAM head. +.TP +.BR EAGAIN " or " ENOSR +.br +Unable to allocate buffers for the acknowledgement message. +.TP +.BR EINVAL +Invalid multiplexer ID number. +.P +An I_PUNLINK can also fail while waiting for the multiplexing driver to +acknowledge the request if a message indicating an error or a hangup is +received at the STREAM head of +.IR fildes . +In addition, an error code can be returned in the positive or negative +acknowledgement message. For these cases, I_PUNLINK shall fail with +.IR errno +set to the value in the message. +.RE +.SH "RETURN VALUE" +Upon successful completion, +\fIioctl\fR() +shall return a value other than \-1 that depends upon the STREAMS device +control function. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +Under the following general conditions, +\fIioctl\fR() +shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EINTR +A signal was caught during the +\fIioctl\fR() +operation. +.TP +.BR EINVAL +The STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.P +If an underlying device driver detects an error, then +\fIioctl\fR() +shall fail if: +.TP +.BR EINVAL +The +.IR request +or +.IR arg +argument is not valid for this device. +.TP +.BR EIO +Some physical I/O error has occurred. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a STREAMS device that accepts control functions. +.TP +.BR ENXIO +The +.IR request +and +.IR arg +arguments are valid for this device driver, but the service requested +cannot be performed on this particular sub-device. +.TP +.BR ENODEV +The +.IR fildes +argument refers to a valid STREAMS device, but the corresponding device +driver does not support the +\fIioctl\fR() +function. +.P +If a STREAM is connected downstream from a multiplexer, any +\fIioctl\fR() +command except I_UNLINK and I_PUNLINK shall set +.IR errno +to +.BR [EINVAL] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The implementation-defined timeout interval for STREAMS has +historically been 15 seconds. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIioctl\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIclose\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isalnum.3p b/upstream/archlinux/man3p/isalnum.3p new file mode 100644 index 00000000..670fec81 --- /dev/null +++ b/upstream/archlinux/man3p/isalnum.3p @@ -0,0 +1,118 @@ +'\" et +.TH ISALNUM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isalnum, +isalnum_l +\(em test for an alphanumeric character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isalnum(int \fIc\fP); +int isalnum_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisalnum\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisalnum\fR() +and +\fIisalnum_l\fR() +functions shall test whether +.IR c +is a character of class +.BR alpha +or +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisalnum_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisalnum\fR() +and +\fIisalnum_l\fR() +functions shall return non-zero if +.IR c +is an alphanumeric character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isalpha.3p b/upstream/archlinux/man3p/isalpha.3p new file mode 100644 index 00000000..ffde26f7 --- /dev/null +++ b/upstream/archlinux/man3p/isalpha.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISALPHA "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isalpha, +isalpha_l +\(em test for an alphabetic character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isalpha(int \fIc\fP); +int isalpha_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisalpha\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisalpha\fR() +and +\fIisalpha_l\fR() +functions shall test whether +.IR c +is a character of class +.BR alpha +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisalpha_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisalpha\fR() +and +\fIisalpha_l\fR() +functions shall return non-zero if +.IR c +is an alphabetic character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isascii.3p b/upstream/archlinux/man3p/isascii.3p new file mode 100644 index 00000000..564c883d --- /dev/null +++ b/upstream/archlinux/man3p/isascii.3p @@ -0,0 +1,73 @@ +'\" et +.TH ISASCII "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isascii +\(em test for a 7-bit US-ASCII character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isascii(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fIisascii\fR() +function shall test whether +.IR c +is a 7-bit US-ASCII character code. +.P +The +\fIisascii\fR() +function is defined on all integer values. +.SH "RETURN VALUE" +The +\fIisascii\fR() +function shall return non-zero if +.IR c +is a 7-bit US-ASCII character code between 0 and octal 0177 inclusive; +otherwise, it shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIisascii\fR() +function cannot be used portably in a localized application. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIisascii\fR() +function may be removed in a future version. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isastream.3p b/upstream/archlinux/man3p/isastream.3p new file mode 100644 index 00000000..967342f4 --- /dev/null +++ b/upstream/archlinux/man3p/isastream.3p @@ -0,0 +1,77 @@ +'\" et +.TH ISASTREAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isastream +\(em test a file descriptor (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int isastream(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIisastream\fR() +function shall test whether +.IR fildes , +an open file descriptor, is associated with a STREAMS-based file. +.SH "RETURN VALUE" +Upon successful completion, +\fIisastream\fR() +shall return 1 if +.IR fildes +refers to a STREAMS-based file and 0 if not. Otherwise, +\fIisastream\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIisastream\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIisastream\fR() +function may be removed in a future version. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isatty.3p b/upstream/archlinux/man3p/isatty.3p new file mode 100644 index 00000000..f686acd8 --- /dev/null +++ b/upstream/archlinux/man3p/isatty.3p @@ -0,0 +1,84 @@ +'\" et +.TH ISATTY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isatty +\(em test for a terminal device +.SH SYNOPSIS +.LP +.nf +#include +.P +int isatty(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIisatty\fR() +function shall test whether +.IR fildes , +an open file descriptor, is associated with a terminal device. +.SH "RETURN VALUE" +The +\fIisatty\fR() +function shall return 1 if +.IR fildes +is associated with a terminal; otherwise, it shall return 0 and may set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIisatty\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIisatty\fR() +function does not necessarily indicate that a human being is available +for interaction via +.IR fildes . +It is quite possible that non-terminal devices are connected to the +communications line. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isblank.3p b/upstream/archlinux/man3p/isblank.3p new file mode 100644 index 00000000..a9e45bd3 --- /dev/null +++ b/upstream/archlinux/man3p/isblank.3p @@ -0,0 +1,119 @@ +'\" et +.TH ISBLANK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isblank, +isblank_l +\(em test for a blank character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isblank(int \fIc\fP); +int isblank_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisblank\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisblank\fR() +and +\fIisblank_l\fR() +functions shall test whether +.IR c +is a character of class +.BR blank +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is a type +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisblank_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisblank\fR() +and +\fIisblank_l\fR() +functions shall return non-zero if +.IR c +is a +; +otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iscntrl.3p b/upstream/archlinux/man3p/iscntrl.3p new file mode 100644 index 00000000..644d23a6 --- /dev/null +++ b/upstream/archlinux/man3p/iscntrl.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISCNTRL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iscntrl, +iscntrl_l +\(em test for a control character +.SH SYNOPSIS +.LP +.nf +#include +.P +int iscntrl(int \fIc\fP); +int iscntrl_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiscntrl\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiscntrl\fR() +and +\fIiscntrl_l\fR() +functions shall test whether +.IR c +is a character of class +.BR cntrl +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is a type +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiscntrl_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiscntrl\fR() +and +\fIiscntrl_l\fR() +functions shall return non-zero if +.IR c +is a control character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isdigit.3p b/upstream/archlinux/man3p/isdigit.3p new file mode 100644 index 00000000..a502709c --- /dev/null +++ b/upstream/archlinux/man3p/isdigit.3p @@ -0,0 +1,115 @@ +'\" et +.TH ISDIGIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isdigit, +isdigit_l +\(em test for a decimal digit +.SH SYNOPSIS +.LP +.nf +#include +.P +int isdigit(int \fIc\fP); +int isdigit_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisdigit\fR() +and +\fIisdigit_l\fR() +functions shall test whether +.IR c +is a character of class +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisdigit\fR() +and +\fIisdigit_l\fR() +functions shall return non-zero if +.IR c +is a decimal digit; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isfinite.3p b/upstream/archlinux/man3p/isfinite.3p new file mode 100644 index 00000000..188c700a --- /dev/null +++ b/upstream/archlinux/man3p/isfinite.3p @@ -0,0 +1,75 @@ +'\" et +.TH ISFINITE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isfinite +\(em test for finite value +.SH SYNOPSIS +.LP +.nf +#include +.P +int isfinite(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisfinite\fR() +macro shall determine whether its argument has a finite value (zero, +subnormal, or normal, and not infinite or NaN). First, an argument +represented in a format wider than its semantic type is converted to +its semantic type. Then determination is based on the type of the +argument. +.SH "RETURN VALUE" +The +\fIisfinite\fR() +macro shall return a non-zero value if and only if its argument has a +finite value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isgraph.3p b/upstream/archlinux/man3p/isgraph.3p new file mode 100644 index 00000000..0c4e9162 --- /dev/null +++ b/upstream/archlinux/man3p/isgraph.3p @@ -0,0 +1,118 @@ +'\" et +.TH ISGRAPH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isgraph, +isgraph_l +\(em test for a visible character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isgraph(int \fIc\fP); +int isgraph_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisgraph\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisgraph\fR() +and +\fIisgraph_l\fR() +functions shall test whether +.IR c +is a character of class +.BR graph +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisgraph_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisgraph\fR() +and +\fIisgraph_l\fR() +functions shall return non-zero if +.IR c +is a character with a visible representation; otherwise, they shall +return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isgreater.3p b/upstream/archlinux/man3p/isgreater.3p new file mode 100644 index 00000000..9bbaea43 --- /dev/null +++ b/upstream/archlinux/man3p/isgreater.3p @@ -0,0 +1,103 @@ +'\" et +.TH ISGREATER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isgreater +\(em test if x greater than y +.SH SYNOPSIS +.LP +.nf +#include +.P +int isgreater(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisgreater\fR() +macro shall determine whether its first argument is greater than its +second argument. The value of +.IR isgreater (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ >\ (\fIy\fR); however, unlike +(\fIx\fR)\ >\ (\fIy\fR), +.IR isgreater (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisgreater\fR() +macro shall return the value of (\fIx\fR)\ >\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isgreaterequal.3p b/upstream/archlinux/man3p/isgreaterequal.3p new file mode 100644 index 00000000..46ae8a8f --- /dev/null +++ b/upstream/archlinux/man3p/isgreaterequal.3p @@ -0,0 +1,103 @@ +'\" et +.TH ISGREATEREQUAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isgreaterequal +\(em test if x is greater than or equal to y +.SH SYNOPSIS +.LP +.nf +#include +.P +int isgreaterequal(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisgreaterequal\fR() +macro shall determine whether its first argument is greater than or +equal to its second argument. The value of +.IR isgreaterequal (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ \(>=\ (\fIy\fR); however, unlike +(\fIx\fR)\ \(>=\ (\fIy\fR), +.IR isgreaterequal (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisgreaterequal\fR() +macro shall return the value of (\fIx\fR)\ \(>=\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isinf.3p b/upstream/archlinux/man3p/isinf.3p new file mode 100644 index 00000000..c22ef86b --- /dev/null +++ b/upstream/archlinux/man3p/isinf.3p @@ -0,0 +1,74 @@ +'\" et +.TH ISINF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isinf +\(em test for infinity +.SH SYNOPSIS +.LP +.nf +#include +.P +int isinf(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisinf\fR() +macro shall determine whether its argument value is an infinity +(positive or negative). First, an argument represented in a format +wider than its semantic type is converted to its semantic type. Then +determination is based on the type of the argument. +.SH "RETURN VALUE" +The +\fIisinf\fR() +macro shall return a non-zero value if and only if its argument has an +infinite value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isless.3p b/upstream/archlinux/man3p/isless.3p new file mode 100644 index 00000000..27dcb820 --- /dev/null +++ b/upstream/archlinux/man3p/isless.3p @@ -0,0 +1,103 @@ +'\" et +.TH ISLESS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isless +\(em test if x is less than y +.SH SYNOPSIS +.LP +.nf +#include +.P +int isless(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisless\fR() +macro shall determine whether its first argument is less than its +second argument. The value of +.IR isless (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ <\ (\fIy\fR); however, unlike +(\fIx\fR)\ <\ (\fIy\fR), +.IR isless (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisless\fR() +macro shall return the value of (\fIx\fR)\ <\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/islessequal.3p b/upstream/archlinux/man3p/islessequal.3p new file mode 100644 index 00000000..96f935b1 --- /dev/null +++ b/upstream/archlinux/man3p/islessequal.3p @@ -0,0 +1,103 @@ +'\" et +.TH ISLESSEQUAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +islessequal +\(em test if x is less than or equal to y +.SH SYNOPSIS +.LP +.nf +#include +.P +int islessequal(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIislessequal\fR() +macro shall determine whether its first argument is less than or equal +to its second argument. The value of +.IR islessequal (\c +.IR x , +.IR y ) +shall be equal to (\fIx\fR)\ <=\ (\fIy\fR); however, unlike +(\fIx\fR)\ <=\ (\fIy\fR), +.IR islessequal (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIislessequal\fR() +macro shall return the value of (\fIx\fR)\ <=\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/islessgreater.3p b/upstream/archlinux/man3p/islessgreater.3p new file mode 100644 index 00000000..aec90a52 --- /dev/null +++ b/upstream/archlinux/man3p/islessgreater.3p @@ -0,0 +1,108 @@ +'\" et +.TH ISLESSGREATER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +islessgreater +\(em test if x is less than or greater than y +.SH SYNOPSIS +.LP +.nf +#include +.P +int islessgreater(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIislessgreater\fR() +macro shall determine whether its first argument is less than or +greater than its second argument. The +.IR islessgreater (\c +.IR x , +.IR y ) +macro is similar to +(\fIx\fR)\ <\ (\fIy\fR)\ ||\ (\fIx\fR)\ >\ (\fIy\fR); however, +.IR islessgreater (\c +.IR x , +.IR y ) +shall not raise the invalid floating-point exception when +.IR x +and +.IR y +are unordered (nor shall it evaluate +.IR x +and +.IR y +twice). +.SH "RETURN VALUE" +Upon successful completion, the +\fIislessgreater\fR() +macro shall return the value of +(\fIx\fR)\ <\ (\fIy\fR)\ ||\ (\fIx\fR)\ >\ (\fIy\fR). +.P +If +.IR x +or +.IR y +is NaN, 0 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIisunordered\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/islower.3p b/upstream/archlinux/man3p/islower.3p new file mode 100644 index 00000000..891b1aed --- /dev/null +++ b/upstream/archlinux/man3p/islower.3p @@ -0,0 +1,171 @@ +'\" et +.TH ISLOWER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +islower, +islower_l +\(em test for a lowercase letter +.SH SYNOPSIS +.LP +.nf +#include +.P +int islower(int \fIc\fP); +int islower_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIislower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIislower\fR() +and +\fIislower_l\fR() +functions shall test whether +.IR c +is a character of class +.BR lower +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIislower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIislower\fR() +and +\fIislower_l\fR() +functions shall return non-zero if +.IR c +is a lowercase letter; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Testing for a Lowercase Letter" +.P +Two examples follow, the first using +\fIislower\fR(), +the second using multiple concurrent locales and +\fIislower_l\fR(). +.P +The examples test whether the value is a lowercase letter, +based on the current locale, then use it as part of a key value. +.sp +.RS 4 +.nf + +/* Example 1 -- using islower() */ +#include +#include +#include +\&... +char *keystr; +int elementlen, len; +unsigned char c; +\&... +setlocale(LC_ALL, ""); +\&... +len = 0; +while (len < elementlen) { + c = (unsigned char) (rand() % 256); +\&... + if (islower(c)) + keystr[len++] = c; + } +\&... +.P +/* Example 2 -- using islower_l() */ +#include +#include +#include +\&... +char *keystr; +int elementlen, len; +unsigned char c; +\&... +locale_t loc = newlocale (LC_ALL_MASK, "", (locale_t) 0); +\&... +len = 0; +while (len < elementlen) { + c = (unsigned char) (rand() % 256); +\&... + if (islower_l(c, loc)) + keystr[len++] = c; + } +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isnan.3p b/upstream/archlinux/man3p/isnan.3p new file mode 100644 index 00000000..06f143d2 --- /dev/null +++ b/upstream/archlinux/man3p/isnan.3p @@ -0,0 +1,74 @@ +'\" et +.TH ISNAN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isnan +\(em test for a NaN +.SH SYNOPSIS +.LP +.nf +#include +.P +int isnan(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisnan\fR() +macro shall determine whether its argument value is a NaN. First, an +argument represented in a format wider than its semantic type is +converted to its semantic type. Then determination is based on the type +of the argument. +.SH "RETURN VALUE" +The +\fIisnan\fR() +macro shall return a non-zero value if and only if its argument has a +NaN value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isnormal.3p b/upstream/archlinux/man3p/isnormal.3p new file mode 100644 index 00000000..c660f8aa --- /dev/null +++ b/upstream/archlinux/man3p/isnormal.3p @@ -0,0 +1,74 @@ +'\" et +.TH ISNORMAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isnormal +\(em test for a normal value +.SH SYNOPSIS +.LP +.nf +#include +.P +int isnormal(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisnormal\fR() +macro shall determine whether its argument value is normal (neither +zero, subnormal, infinite, nor NaN). First, an argument represented in +a format wider than its semantic type is converted to its semantic +type. Then determination is based on the type of the argument. +.SH "RETURN VALUE" +The +\fIisnormal\fR() +macro shall return a non-zero value if and only if its argument has a +normal value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIsignbit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isprint.3p b/upstream/archlinux/man3p/isprint.3p new file mode 100644 index 00000000..b45dd208 --- /dev/null +++ b/upstream/archlinux/man3p/isprint.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISPRINT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isprint, +isprint_l +\(em test for a printable character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isprint(int \fIc\fP); +int isprint_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisprint\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisprint\fR() +and +\fIisprint_l\fR() +functions shall test whether +.IR c +is a character of class +.BR print +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisprint_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisprint\fR() +and +\fIisprint_l\fR() +functions shall return non-zero if +.IR c +is a printable character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ispunct.3p b/upstream/archlinux/man3p/ispunct.3p new file mode 100644 index 00000000..efd12ceb --- /dev/null +++ b/upstream/archlinux/man3p/ispunct.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISPUNCT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ispunct, +ispunct_l +\(em test for a punctuation character +.SH SYNOPSIS +.LP +.nf +#include +.P +int ispunct(int \fIc\fP); +int ispunct_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIispunct\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIispunct\fR() +and +\fIispunct_l\fR() +functions shall test whether +.IR c +is a character of class +.BR punct +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIispunct_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIispunct\fR() +and +\fIispunct_l\fR() +functions shall return non-zero if +.IR c +is a punctuation character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isspace.3p b/upstream/archlinux/man3p/isspace.3p new file mode 100644 index 00000000..581fde62 --- /dev/null +++ b/upstream/archlinux/man3p/isspace.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISSPACE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isspace, +isspace_l +\(em test for a white-space character +.SH SYNOPSIS +.LP +.nf +#include +.P +int isspace(int \fIc\fP); +int isspace_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisspace\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisspace\fR() +and +\fIisspace_l\fR() +functions shall test whether +.IR c +is a character of class +.BR space +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisspace_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisspace\fR() +and +\fIisspace_l\fR() +functions shall return non-zero if +.IR c +is a white-space character; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isunordered.3p b/upstream/archlinux/man3p/isunordered.3p new file mode 100644 index 00000000..18247140 --- /dev/null +++ b/upstream/archlinux/man3p/isunordered.3p @@ -0,0 +1,89 @@ +'\" et +.TH ISUNORDERED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isunordered +\(em test if arguments are unordered +.SH SYNOPSIS +.LP +.nf +#include +.P +int isunordered(real-floating \fIx\fP, real-floating \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisunordered\fR() +macro shall determine whether its arguments are unordered. +.SH "RETURN VALUE" +Upon successful completion, the +\fIisunordered\fR() +macro shall return 1 if its arguments are unordered, and 0 otherwise. +.P +If +.IR x +or +.IR y +is NaN, 1 shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The relational and equality operators support the usual mathematical +relationships between numeric values. For any ordered pair of numeric +values, exactly one of the relationships (less, greater, and equal) is +true. Relational operators may raise the invalid floating-point +exception when argument values are NaNs. For a NaN and a numeric value, +or for two NaNs, just the unordered relationship is true. This macro +is a quiet (non-floating-point exception raising) version of a +relational operator. It facilitates writing efficient code that +accounts for NaNs without suffering the invalid floating-point +exception. In the SYNOPSIS section, +.BR real-floating +indicates that the argument shall be an expression of +.BR real-floating +type. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisgreater\fR\^(\|)", +.IR "\fIisgreaterequal\fR\^(\|)", +.IR "\fIisless\fR\^(\|)", +.IR "\fIislessequal\fR\^(\|)", +.IR "\fIislessgreater\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isupper.3p b/upstream/archlinux/man3p/isupper.3p new file mode 100644 index 00000000..cb01f487 --- /dev/null +++ b/upstream/archlinux/man3p/isupper.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISUPPER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isupper, +isupper_l +\(em test for an uppercase letter +.SH SYNOPSIS +.LP +.nf +#include +.P +int isupper(int \fIc\fP); +int isupper_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisupper\fR() +and +\fIisupper_l\fR() +functions shall test whether +.IR c +is a character of class +.BR upper +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisupper\fR() +and +\fIisupper_l\fR() +functions shall return non-zero if +.IR c +is an uppercase letter; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswalnum.3p b/upstream/archlinux/man3p/iswalnum.3p new file mode 100644 index 00000000..fd602d02 --- /dev/null +++ b/upstream/archlinux/man3p/iswalnum.3p @@ -0,0 +1,119 @@ +'\" et +.TH ISWALNUM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswalnum, +iswalnum_l +\(em test for an alphanumeric wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswalnum(wint_t \fIwc\fP); +int iswalnum_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswalnum\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswalnum\fR() +and +\fIiswalnum_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR alpha +or +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswalnum_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswalnum\fR() +and +\fIiswalnum_l\fR() +functions shall return non-zero if +.IR wc +is an alphanumeric wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswalpha.3p b/upstream/archlinux/man3p/iswalpha.3p new file mode 100644 index 00000000..5a34ee21 --- /dev/null +++ b/upstream/archlinux/man3p/iswalpha.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWALPHA "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswalpha, +iswalpha_l +\(em test for an alphabetic wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswalpha(wint_t \fIwc\fP); +int iswalpha_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswalpha\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswalpha\fR() +and +\fIiswalpha_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR alpha +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswalpha_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswalpha\fR() +and +\fIiswalpha_l\fR() +functions shall return non-zero if +.IR wc +is an alphabetic wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswblank.3p b/upstream/archlinux/man3p/iswblank.3p new file mode 100644 index 00000000..c6a92f34 --- /dev/null +++ b/upstream/archlinux/man3p/iswblank.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISWBLANK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswblank, +iswblank_l +\(em test for a blank wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswblank(wint_t \fIwc\fP); +int iswblank_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswblank\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswblank\fR() +and +\fIiswblank\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR blank +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswblank_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswblank\fR() +and +\fIiswblank_l\fR() +functions shall return non-zero if +.IR wc +is a blank wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswcntrl.3p b/upstream/archlinux/man3p/iswcntrl.3p new file mode 100644 index 00000000..e2578e4e --- /dev/null +++ b/upstream/archlinux/man3p/iswcntrl.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWCNTRL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswcntrl, +iswcntrl_l +\(em test for a control wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswcntrl(wint_t \fIwc\fP); +int iswcntrl_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswcntrl\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswcntrl\fR() +and +\fIiswcntrl_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR cntrl +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswcntrl_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswcntrl\fR() +and +\fIiswcntrl_l\fR() +functions shall return non-zero if +.IR wc +is a control wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswctype.3p b/upstream/archlinux/man3p/iswctype.3p new file mode 100644 index 00000000..1036843c --- /dev/null +++ b/upstream/archlinux/man3p/iswctype.3p @@ -0,0 +1,192 @@ +'\" et +.TH ISWCTYPE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswctype, +iswctype_l +\(em test character for a specified class +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswctype(wint_t \fIwc\fP, wctype_t \fIcharclass\fP); +int iswctype_l(wint_t \fIwc\fP, wctype_t \fIcharclass\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswctype\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswctype\fR() +and +\fIiswctype_l\fR() +functions shall determine whether the wide-character code +.IR wc +has the character class +.IR charclass , +returning true or false. The +\fIiswctype\fR() +and +\fIiswctype_l\fR() +functions are defined on WEOF and wide-character codes corresponding to +the valid character encodings in the current locale, or +in the locale represented by +.IR locale , +respectively. If the +.IR wc +argument is not in the domain of the function, the result is undefined. +If the value of +.IR charclass +is invalid (that is, not obtained by a call to +\fIwctype\fR() +or +.IR charclass +is invalidated by a subsequent call to +\fIsetlocale\fR() +that has affected category +.IR LC_CTYPE ) +the result is unspecified. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswctype_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswctype\fR() +and +\fIiswctype_l\fR() +functions shall return non-zero (true) if and only if +.IR wc +has the property described by +.IR charclass . +If +.IR charclass +is (\c +.BR wctype_t )0, +these functions shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Testing for a Valid Character" +.sp +.RS 4 +.nf + +#include +\&... +int yes_or_no; +wint_t wc; +wctype_t valid_class; +\&... +if ((valid_class=wctype("vowel")) == (wctype_t)0) + /* Invalid character class. */ +yes_or_no=iswctype(wc,valid_class); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The twelve strings +.BR \(dqalnum\(dq , +.BR \(dqalpha\(dq , +.BR \(dqblank\(dq , +.BR \(dqcntrl\(dq , +.BR \(dqdigit\(dq , +.BR \(dqgraph\(dq , +.BR \(dqlower\(dq , +.BR \(dqprint\(dq , +.BR \(dqpunct\(dq , +.BR \(dqspace\(dq , +.BR \(dqupper\(dq , +and +.BR \(dqxdigit\(dq +are reserved for the standard character classes. In the table below, +the functions in the left column are equivalent to the functions in the +right column. +.sp +.RS 4 +.nf + +iswalnum(\fIwc\fP) iswctype(\fIwc\fP, wctype("alnum")) +iswalnum_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("alnum"), \fIlocale\fP) +iswalpha(\fIwc\fP) iswctype(\fIwc\fP, wctype("alpha")) +iswalpha_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("alpha"), \fIlocale\fP) +iswblank(\fIwc\fP) iswctype(\fIwc\fP, wctype("blank")) +iswblank_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("blank"), \fIlocale\fP) +iswcntrl(\fIwc\fP) iswctype(\fIwc\fP, wctype("cntrl")) +iswcntrl_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("cntrl"), \fIlocale\fP) +iswdigit(\fIwc\fP) iswctype(\fIwc\fP, wctype("digit")) +iswdigit_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("digit"), \fIlocale\fP) +iswgraph(\fIwc\fP) iswctype(\fIwc\fP, wctype("graph")) +iswgraph_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("graph"), \fIlocale\fP) +iswlower(\fIwc\fP) iswctype(\fIwc\fP, wctype("lower")) +iswlower_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("lower"), \fIlocale\fP) +iswprint(\fIwc\fP) iswctype(\fIwc\fP, wctype("print")) +iswprint_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("print"), \fIlocale\fP) +iswpunct(\fIwc\fP) iswctype(\fIwc\fP, wctype("punct")) +iswpunct_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("punct"), \fIlocale\fP) +iswspace(\fIwc\fP) iswctype(\fIwc\fP, wctype("space")) +iswspace_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("space"), \fIlocale\fP) +iswupper(\fIwc\fP) iswctype(\fIwc\fP, wctype("upper")) +iswupper_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("upper"), \fIlocale\fP) +iswxdigit(\fIwc\fP) iswctype(\fIwc\fP, wctype("xdigit")) +iswxdigit_l(\fIwc\fP, \fIlocale\fP) iswctype_l(\fIwc\fP, wctype("xdigit"), \fIlocale\fP) +.fi +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)", +.IR "\fIwctype\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswdigit.3p b/upstream/archlinux/man3p/iswdigit.3p new file mode 100644 index 00000000..0482ab59 --- /dev/null +++ b/upstream/archlinux/man3p/iswdigit.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWDIGIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswdigit, +iswdigit_l +\(em test for a decimal digit wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswdigit(wint_t \fIwc\fP); +int iswdigit_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswdigit\fR() +and +\fIiswdigit_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR digit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswdigit\fR() +and +\fIiswdigit_l\fR() +functions shall return non-zero if +.IR wc +is a decimal digit wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswgraph.3p b/upstream/archlinux/man3p/iswgraph.3p new file mode 100644 index 00000000..6de85812 --- /dev/null +++ b/upstream/archlinux/man3p/iswgraph.3p @@ -0,0 +1,117 @@ +'\" et +.TH ISWGRAPH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswgraph, +iswgraph_l +\(em test for a visible wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswgraph(wint_t \fIwc\fP); +int iswgraph_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswgraph\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswgraph\fR() +and +\fIiswgraph_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR graph +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswgraph_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswgraph\fR() +and +\fIiswgraph_l\fR() +functions shall return non-zero if +.IR wc +is a wide-character code with a visible representation; otherwise, they +shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswlower.3p b/upstream/archlinux/man3p/iswlower.3p new file mode 100644 index 00000000..5008caec --- /dev/null +++ b/upstream/archlinux/man3p/iswlower.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWLOWER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswlower, +iswlower_l +\(em test for a lowercase letter wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswlower(wint_t \fIwc\fP); +int iswlower_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswlower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswlower\fR() +and +\fIiswlower_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR lower +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswlower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswlower\fR() +and +\fIiswlower_l\fR() +functions shall return non-zero if +.IR wc +is a lowercase letter wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)"1 +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswprint.3p b/upstream/archlinux/man3p/iswprint.3p new file mode 100644 index 00000000..b8c7e5f9 --- /dev/null +++ b/upstream/archlinux/man3p/iswprint.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWPRINT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswprint, +iswprint_l +\(em test for a printable wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswprint(wint_t \fIwc\fP); +int iswprint_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswprint\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswprint\fR() +and +\fIiswprint_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR print +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswprint_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswprint\fR() +and +\fIiswprint_l\fR() +functions shall return non-zero if +.IR wc +is a printable wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswpunct.3p b/upstream/archlinux/man3p/iswpunct.3p new file mode 100644 index 00000000..38589ff4 --- /dev/null +++ b/upstream/archlinux/man3p/iswpunct.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWPUNCT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswpunct, +iswpunct_l +\(em test for a punctuation wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswpunct(wint_t \fIwc\fP); +int iswpunct_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswpunct\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswpunct\fR() +and +\fIiswpunct_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR punct +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswpunct_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswpunct\fR() +and +\fIiswpunct_l\fR() +functions shall return non-zero if +.IR wc +is a punctuation wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswspace.3p b/upstream/archlinux/man3p/iswspace.3p new file mode 100644 index 00000000..ef598734 --- /dev/null +++ b/upstream/archlinux/man3p/iswspace.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWSPACE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswspace, +iswspace_l +\(em test for a white-space wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswspace(wint_t \fIwc\fP); +int iswspace_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswspace\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswspace\fR() +and +\fIiswspace_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR space +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswspace_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswspace\fR() +and +\fIiswspace_l\fR() +functions shall return non-zero if +.IR wc +is a white-space wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswupper.3p b/upstream/archlinux/man3p/iswupper.3p new file mode 100644 index 00000000..4e74f243 --- /dev/null +++ b/upstream/archlinux/man3p/iswupper.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWUPPER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswupper, +iswupper_l +\(em test for an uppercase letter wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswupper(wint_t \fIwc\fP); +int iswupper_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswupper\fR() +and +\fIiswupper_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR upper +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswupper\fR() +and +\fIiswupper_l\fR() +functions shall return non-zero if +.IR wc +is an uppercase letter wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/iswxdigit.3p b/upstream/archlinux/man3p/iswxdigit.3p new file mode 100644 index 00000000..323f287b --- /dev/null +++ b/upstream/archlinux/man3p/iswxdigit.3p @@ -0,0 +1,116 @@ +'\" et +.TH ISWXDIGIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +iswxdigit, +iswxdigit_l +\(em test for a hexadecimal digit wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int iswxdigit(wint_t \fIwc\fP); +int iswxdigit_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIiswxdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIiswxdigit\fR() +and +\fIiswxdigit_l\fR() +functions shall test whether +.IR wc +is a wide-character code representing a character of class +.BR xdigit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR wc +argument is a +.BR wint_t , +the value of which the application shall ensure is a wide-character +code corresponding to a valid character in the locale used by the +function, or equal to the value of the macro WEOF. If the argument +has any other value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIiswxdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIiswxdigit\fR() +and +\fIiswxdigit_l\fR() +functions shall return non-zero if +.IR wc +is a hexadecimal digit wide-character code; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/isxdigit.3p b/upstream/archlinux/man3p/isxdigit.3p new file mode 100644 index 00000000..f2c2e58e --- /dev/null +++ b/upstream/archlinux/man3p/isxdigit.3p @@ -0,0 +1,114 @@ +'\" et +.TH ISXDIGIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +isxdigit, +isxdigit_l +\(em test for a hexadecimal digit +.SH SYNOPSIS +.LP +.nf +#include +.P +int isxdigit(int \fIc\fP); +int isxdigit_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIisxdigit\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIisxdigit\fR() +and +\fIisxdigit_l\fR() +functions shall test whether +.IR c +is a character of class +.BR xdigit +in the current locale, +or in the locale represented by +.IR locale , +respectively; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale". +.P +The +.IR c +argument is an +.BR int , +the value of which the application shall ensure is a character +representable as an +.BR "unsigned char" +or equal to the value of the macro EOF. If the argument has any other +value, the behavior is undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIisxdigit_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIisxdigit\fR() +and +\fIisxdigit_l\fR() +functions shall return non-zero if +.IR c +is a hexadecimal digit; otherwise, they shall return 0. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +To ensure applications portability, especially across natural +languages, only these functions and the functions in the reference pages +listed in the SEE ALSO section should be used for character classification. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/j0.3p b/upstream/archlinux/man3p/j0.3p new file mode 100644 index 00000000..d8d2f4eb --- /dev/null +++ b/upstream/archlinux/man3p/j0.3p @@ -0,0 +1,114 @@ +'\" et +.TH J0 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +j0, +j1, +jn +\(em Bessel functions of the first kind +.SH SYNOPSIS +.LP +.nf +#include +.P +double j0(double \fIx\fP); +double j1(double \fIx\fP); +double jn(int \fIn\fP, double \fIx\fP); +.fi +.SH DESCRIPTION +The +\fIj0\fR(), +\fIj1\fR(), +and +\fIjn\fR() +functions shall compute Bessel functions of +.IR x +of the first kind of orders 0, 1, and +.IR n , +respectively. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the relevant +Bessel value of +.IR x +of the first kind. +.P +If the +.IR x +argument is too large in magnitude, or the correct result would cause +underflow, 0 shall be returned and a range error may occur. +.P +If +.IR x +is NaN, a NaN shall be returned. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +was too large in magnitude, or an underflow occurred. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.P +No other errors shall occur. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIy0\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/jrand48.3p b/upstream/archlinux/man3p/jrand48.3p new file mode 100644 index 00000000..738a5894 --- /dev/null +++ b/upstream/archlinux/man3p/jrand48.3p @@ -0,0 +1,40 @@ +'\" et +.TH JRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +jrand48 +\(em generate a uniformly distributed pseudo-random long signed integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long jrand48(unsigned short \fIxsubi\fR[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/kill.3p b/upstream/archlinux/man3p/kill.3p new file mode 100644 index 00000000..8d64a257 --- /dev/null +++ b/upstream/archlinux/man3p/kill.3p @@ -0,0 +1,290 @@ +'\" et +.TH KILL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +kill +\(em send a signal to a process or a group of processes +.SH SYNOPSIS +.LP +.nf +#include +.P +int kill(pid_t \fIpid\fP, int \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIkill\fR() +function shall send a signal to a process or a group of processes +specified by +.IR pid . +The signal to be sent is specified by +.IR sig +and is either one from the list given in +.IR +or 0. If +.IR sig +is 0 (the null signal), error checking is performed but no signal is +actually sent. The null signal can be used to check the validity of +.IR pid . +.P +For a process to have permission to send a signal to a process +designated by +.IR pid , +unless the sending process has appropriate privileges, the real or +effective user ID of the sending process shall match the real or saved +set-user-ID of the receiving process. +.P +If +.IR pid +is greater than 0, +.IR sig +shall be sent to the process whose process ID is equal to +.IR pid . +.P +If +.IR pid +is 0, +.IR sig +shall be sent to all processes (excluding an unspecified set of system +processes) whose process group ID is equal to the process group ID of +the sender, and for which the process has permission to send a signal. +.P +If +.IR pid +is \-1, +.IR sig +shall be sent to all processes (excluding an unspecified set of system +processes) for which the process has permission to send that signal. +.P +If +.IR pid +is negative, but not \-1, +.IR sig +shall be sent to all processes (excluding an unspecified set of system +processes) whose process group ID is equal to the absolute value of +.IR pid , +and for which the process has permission to send a signal. +.P +If the value of +.IR pid +causes +.IR sig +to be generated for the sending process, and if +.IR sig +is not blocked for the calling thread and if no other thread has +.IR sig +unblocked or is waiting in a +\fIsigwait\fR() +function for +.IR sig , +either +.IR sig +or at least one pending unblocked signal shall be delivered to the +sending thread before +\fIkill\fR() +returns. +.P +The user ID tests described above shall not be applied when sending +SIGCONT to a process that is a member of the same session as the +sending process. +.P +An implementation that provides extended security controls may impose +further implementation-defined restrictions on the sending of +signals, including the null signal. In particular, the system may deny +the existence of some or all of the processes specified by +.IR pid . +.P +The +\fIkill\fR() +function is successful if the process has permission to send +.IR sig +to any of the processes specified by +.IR pid . +If +\fIkill\fR() +fails, no signal shall be sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIkill\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR sig +argument is an invalid or unsupported signal number. +.TP +.BR EPERM +The process does not have permission to send the signal to any +receiving process. +.TP +.BR ESRCH +No process or process group can be found corresponding to that +specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The semantics for permission checking for +\fIkill\fR() +differed between System V and most other implementations, such as +Version 7 or +4.3 BSD. The semantics chosen for this volume of POSIX.1\(hy2017 agree with System V. +Specifically, a set-user-ID +process cannot protect itself against signals (or at least not against +SIGKILL) +unless it changes its real user ID. +This choice allows the user who starts an application to send it +signals even if it changes its effective user ID. +The other semantics give more power to an application that wants to +protect itself from the user who ran it. +.P +Some implementations provide semantic extensions to the +\fIkill\fR() +function when the absolute value of +.IR pid +is greater than some maximum, or otherwise special, value. Negative +values are a flag to +\fIkill\fR(). +Since most implementations return +.BR [ESRCH] +in this case, this behavior is not included in this volume of POSIX.1\(hy2017, although +a conforming implementation could provide such an extension. +.P +The unspecified processes to which a signal cannot be sent +may include the scheduler or +.IR init . +.P +There was initially strong sentiment to specify that, if +.IR pid +specifies that a signal be sent to the calling process and that signal +is not blocked, that signal would be delivered before +\fIkill\fR() +returns. This would permit a process to call +\fIkill\fR() +and be guaranteed that the call never return. However, historical +implementations that provide only the +\fIsignal\fR() +function make only the weaker guarantee in this volume of POSIX.1\(hy2017, because they +only deliver one signal each time a process enters the kernel. +Modifications to such implementations to support the +\fIsigaction\fR() +function generally require entry to the kernel following return from a +signal-catching function, in order to restore the signal mask. Such +modifications have the effect of satisfying the stronger requirement, +at least when +\fIsigaction\fR() +is used, but not necessarily when +\fIsignal\fR() +is used. The standard developers considered making the +stronger requirement except when +\fIsignal\fR() +is used, but felt this would be unnecessarily complex. Implementors +are encouraged to meet the stronger requirement whenever possible. In +practice, the weaker requirement is the same, except in the rare case +when two signals arrive during a very short window. This reasoning +also applies to a similar requirement for +\fIsigprocmask\fR(). +.P +In 4.2 BSD, the SIGCONT +signal can be sent to any descendant process regardless of user-ID +security checks. +This allows a job control shell to continue a job even if processes in +the +job have altered their user IDs (as in the +.IR su +command). In keeping with the addition of the concept of sessions, +similar functionality is provided by allowing the SIGCONT +signal to be sent to any process in the same session regardless of user +ID security checks. This is less restrictive than BSD in the sense +that ancestor processes (in the same session) can now be the recipient. +It is more restrictive than BSD in the sense that descendant processes +that form new sessions are now subject to the user ID checks. A similar +relaxation of security is not necessary for the other job control +signals since those signals are typically sent by the terminal driver +in recognition of special characters being typed; the terminal driver +bypasses all security checks. +.P +In secure implementations, a process may be restricted +from sending a signal to a process having a different security label. +In order to prevent the existence or nonexistence of a process from +being used as a covert channel, +such processes should appear nonexistent to the sender; that is, +.BR [ESRCH] +should be returned, rather than +.BR [EPERM] , +if +.IR pid +refers only to such processes. +.P +Historical implementations varied on the result of a +\fIkill\fR() +with +.IR pid +indicating a zombie process. Some indicated success on such a call +(subject to permission checking), while others gave an error of +.BR [ESRCH] . +Since the definition of process lifetime in this volume of POSIX.1\(hy2017 +covers zombie processes, the +.BR [ESRCH] +error as described is inappropriate in this case and implementations +that give this error do not conform. This means that an application +cannot have a parent process check for termination of a particular +child by sending it the null signal with +\fIkill\fR(), +but must instead use +\fIwaitpid\fR() +or +\fIwaitid\fR(). +.P +There is some belief that the name +\fIkill\fR() +is misleading, since the function is not always intended to cause +process termination. However, the name is common to all historical +implementations, and any change would be in conflict with the goal of +minimal changes to existing application code. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigqueue\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/killpg.3p b/upstream/archlinux/man3p/killpg.3p new file mode 100644 index 00000000..56d7c3df --- /dev/null +++ b/upstream/archlinux/man3p/killpg.3p @@ -0,0 +1,97 @@ +'\" et +.TH KILLPG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +killpg +\(em send a signal to a process group +.SH SYNOPSIS +.LP +.nf +#include +.P +int killpg(pid_t \fIpgrp\fP, int \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIkillpg\fR() +function shall send the signal specified by +.IR sig +to the process group specified by +.IR pgrp . +.P +If +.IR pgrp +is greater than 1, \fIkillpg\fP(\fIpgrp\fP,\ \fIsig\fR) shall be +equivalent to \fIkill\fP(\-\fIpgrp\fP,\ \fIsig\fR). If +.IR pgrp +is less than or equal to 1, the behavior of +\fIkillpg\fR() +is undefined. +.SH "RETURN VALUE" +Refer to +.IR "\fIkill\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIkill\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending a Signal to All Other Members of a Process Group" +.P +The following example shows how the calling process could send a signal +to all other members of its process group. To prevent itself from +receiving the signal it first makes itself immune to the signal by +ignoring it. +.sp +.RS 4 +.nf + +#include +#include +\&... + if (signal(SIGUSR1, SIG_IGN) == SIG_ERR) + /* Handle error */; +.P + if (killpg(getpgrp(), SIGUSR1) == -1) + /* Handle error */;" +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpgid\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIraise\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/l64a.3p b/upstream/archlinux/man3p/l64a.3p new file mode 100644 index 00000000..eca9338b --- /dev/null +++ b/upstream/archlinux/man3p/l64a.3p @@ -0,0 +1,40 @@ +'\" et +.TH L64A "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +l64a +\(em convert a 32-bit integer to a radix-64 ASCII string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *l64a(long \fIvalue\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIa64l\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/labs.3p b/upstream/archlinux/man3p/labs.3p new file mode 100644 index 00000000..33b74e6b --- /dev/null +++ b/upstream/archlinux/man3p/labs.3p @@ -0,0 +1,86 @@ +'\" et +.TH LABS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +labs, +llabs +\(em return a long integer absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +long labs(long \fIi\fP); +long long llabs(long long \fIi\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIlabs\fR() +function shall compute the absolute value of the +.BR long +integer operand +.IR i . +The +\fIllabs\fR() +function shall compute the absolute value of the +.BR "long long" +integer operand +.IR i . +If the result cannot be represented, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIlabs\fR() +function shall return the absolute value of the +.BR long +integer operand. +.P +The +\fIllabs\fR() +function shall return the absolute value of the +.BR "long long" +integer operand. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lchown.3p b/upstream/archlinux/man3p/lchown.3p new file mode 100644 index 00000000..5e0bdfca --- /dev/null +++ b/upstream/archlinux/man3p/lchown.3p @@ -0,0 +1,176 @@ +'\" et +.TH LCHOWN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lchown +\(em change the owner and group of a symbolic link +.SH SYNOPSIS +.LP +.nf +#include +.P +int lchown(const char *\fIpath\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +.fi +.SH DESCRIPTION +The +\fIlchown\fR() +function shall be equivalent to +\fIchown\fR(), +except in the case where the named file is a symbolic link. In this +case, +\fIlchown\fR() +shall change the ownership of the symbolic link file itself, while +\fIchown\fR() +changes the ownership of the file or directory to which the symbolic +link refers. +.SH "RETURN VALUE" +Upon successful completion, +\fIlchown\fR() +shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate an error. +.SH ERRORS +The +\fIlchown\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix of +.IR path . +.TP +.BR EINVAL +The owner or group ID is not a value supported by the implementation. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The effective user ID does not match the owner of the file and the +process does not have appropriate privileges. +.TP +.BR EROFS +The file resides on a read-only file system. +.P +The +\fIlchown\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading or writing to the file system. +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Current Owner of a File" +.P +The following example shows how to change the ownership of the symbolic +link named +.BR /modules/pass1 +to the user ID associated with ``jones'' and the group ID associated +with ``cnd''. +.P +The numeric value for the user ID is obtained by using the +\fIgetpwnam\fR() +function. The numeric value for the group ID is obtained by using the +\fIgetgrnam\fR() +function. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +.P +struct passwd *pwd; +struct group *grp; +char *path = "/modules/pass1"; +\&... +pwd = getpwnam("jones"); +grp = getgrnam("cnd"); +lchown(path, pwd->pw_uid, grp->gr_gid); +.fi +.P +.RE +.SH "APPLICATION USAGE" +On implementations which support symbolic links as directory entries +rather than files, +\fIlchown\fR() +may fail. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchown\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lcong48.3p b/upstream/archlinux/man3p/lcong48.3p new file mode 100644 index 00000000..c7d25e2a --- /dev/null +++ b/upstream/archlinux/man3p/lcong48.3p @@ -0,0 +1,41 @@ +'\" et +.TH LCONG48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lcong48 +\(em seed a uniformly distributed pseudo-random signed long +integer generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void lcong48(unsigned short \fIparam\fP[7]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ldexp.3p b/upstream/archlinux/man3p/ldexp.3p new file mode 100644 index 00000000..86196d94 --- /dev/null +++ b/upstream/archlinux/man3p/ldexp.3p @@ -0,0 +1,153 @@ +'\" et +.TH LDEXP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ldexp, +ldexpf, +ldexpl +\(em load exponent of a floating-point number +.SH SYNOPSIS +.LP +.nf +#include +.P +double ldexp(double \fIx\fP, int \fIexp\fP); +float ldexpf(float \fIx\fP, int \fIexp\fP); +long double ldexpl(long double \fIx\fP, int \fIexp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the quantity +\fIx\fR\ *\ 2\u\s-3\fIexp\fR\s+3\d. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +.IR x +multiplied by 2, raised to the power +.IR exp . +.P +If these functions would cause overflow, a range error shall occur and +\fIldexp\fR(), +\fIldexpf\fR(), +and +\fIldexpl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (according +to the sign of +.IR x ), +respectively. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIldexp\fR(), +\fIldexpf\fR(), +and +\fIldexpl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR exp +is 0, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfrexp\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ldiv.3p b/upstream/archlinux/man3p/ldiv.3p new file mode 100644 index 00000000..e6cca7a6 --- /dev/null +++ b/upstream/archlinux/man3p/ldiv.3p @@ -0,0 +1,110 @@ +'\" et +.TH LDIV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ldiv, +lldiv +\(em compute quotient and remainder of a long division +.SH SYNOPSIS +.LP +.nf +#include +.P +ldiv_t ldiv(long \fInumer\fP, long \fIdenom\fP); +lldiv_t lldiv(long long \fInumer\fP, long long \fIdenom\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the quotient and remainder of the +division of the numerator +.IR numer +by the denominator +.IR denom . +If the division is inexact, the resulting quotient is the +.BR long +integer (for the +\fIldiv\fR() +function) or +.BR "long long" +integer (for the +\fIlldiv\fR() +function) of lesser magnitude that is the nearest to the algebraic +quotient. If the result cannot be represented, the behavior is +undefined; otherwise, \fIquot\fP\ *\ \fIdenom\fP+\fIrem\fP shall equal +.IR numer . +.SH "RETURN VALUE" +The +\fIldiv\fR() +function shall return a structure of type +.BR ldiv_t , +comprising both the quotient and the remainder. The structure shall +include the following members, in any order: +.sp +.RS 4 +.nf + +long quot; /* Quotient */ +long rem; /* Remainder */ +.fi +.P +.RE +.P +The +\fIlldiv\fR() +function shall return a structure of type +.BR lldiv_t , +comprising both the quotient and the remainder. The structure shall +include the following members, in any order: +.sp +.RS 4 +.nf + +long long quot; /* Quotient */ +long long rem; /* Remainder */ +.fi +.P +.RE +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lfind.3p b/upstream/archlinux/man3p/lfind.3p new file mode 100644 index 00000000..2d348739 --- /dev/null +++ b/upstream/archlinux/man3p/lfind.3p @@ -0,0 +1,41 @@ +'\" et +.TH LFIND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lfind +\(em find entry in a linear search table +.SH SYNOPSIS +.LP +.nf +#include +.P +void *lfind(const void *\fIkey\fP, const void *\fIbase\fP, size_t *\fInelp\fP, + size_t \fIwidth\fP, int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlsearch\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lgamma.3p b/upstream/archlinux/man3p/lgamma.3p new file mode 100644 index 00000000..ab25a81b --- /dev/null +++ b/upstream/archlinux/man3p/lgamma.3p @@ -0,0 +1,160 @@ +'\" et +.TH LGAMMA "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.EQ +delim $$ +.EN +.SH NAME +lgamma, +lgammaf, +lgammal, +signgam +\(em log gamma function +.SH SYNOPSIS +.LP +.nf +#include +.P +double lgamma(double \fIx\fP); +float lgammaf(float \fIx\fP); +long double lgammal(long double \fIx\fP); +extern int signgam; +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute +$log_ e" " \(br \(*G ( ^ x ) \(br$ +where $\(*G ( ^ x )$ is defined as +$int from 0 to inf e"^" " "{ - t } t"^" " "{ x - 1 } dt$. +The argument +.IR x +need not be a non-positive integer ($\(*G( ^ x )$ is defined over +the reals, except the non-positive integers). +.P +If +.IR x +is NaN, \-Inf, or a negative integer, the value of +.IR signgam +is unspecified. +.P +These functions need not be thread-safe. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the +logarithmic gamma of +.IR x . +.P +If +.IR x +is a non-positive integer, a pole error shall occur and +\fIlgamma\fR(), +\fIlgammaf\fR(), +and +\fIlgammal\fR() +shall return +HUGE_VAL, +HUGE_VALF, and +HUGE_VALL, respectively. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIlgamma\fR(), +\fIlgammaf\fR(), +and +\fIlgammal\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (having the +same sign as the correct value), respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1 or 2, +0 shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Pole\ Error" 12 +The +.IR x +argument is a negative integer or zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/link.3p b/upstream/archlinux/man3p/link.3p new file mode 100644 index 00000000..846a6fca --- /dev/null +++ b/upstream/archlinux/man3p/link.3p @@ -0,0 +1,470 @@ +'\" et +.TH LINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +link, linkat +\(em link one file to another file +.SH SYNOPSIS +.LP +.nf +#include +.P +int link(const char *\fIpath1\fP, const char *\fIpath2\fP); +.P +#include +.P +int linkat(int \fIfd1\fP, const char *\fIpath1\fP, int \fIfd2\fP, + const char *\fIpath2\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIlink\fR() +function shall create a new link (directory entry) for the existing file, +.IR path1 . +.P +The +.IR path1 +argument points to a pathname naming an existing file. The +.IR path2 +argument points to a pathname naming the new directory entry to be +created. The +\fIlink\fR() +function shall atomically create a new link for the existing file and +the link count of the file shall be incremented by one. +.P +If +.IR path1 +names a directory, +\fIlink\fR() +shall fail unless the process has appropriate privileges and the +implementation supports using +\fIlink\fR() +on directories. +.P +If +.IR path1 +names a symbolic link, it is implementation-defined whether +\fIlink\fR() +follows the symbolic link, or creates a new link to the symbolic +link itself. +.P +Upon successful completion, +\fIlink\fR() +shall mark for update the last file status change timestamp of the +file. Also, the last data modification and last file status change +timestamps of the directory that contains the new entry shall be marked +for update. +.P +If +\fIlink\fR() +fails, no link shall be created and the link count of the file shall +remain unchanged. +.P +The implementation may require that the calling process has permission +to access the existing file. +.P +The +\fIlinkat\fR() +function shall be equivalent to the +\fIlink\fR() +function except that symbolic links shall be handled as specified by +the value of +.IR flag +(see below) and except in the case where either +.IR path1 +or +.IR path2 +or both are relative paths. In this case a relative path +.IR path1 +is interpreted relative to the directory associated with the file +descriptor +.IR fd1 +instead of the current working directory and similarly for +.IR path2 +and the file descriptor +.IR fd2 . +If the access mode of the open file description associated with the +file descriptor is not O_SEARCH, the function shall check whether +directory searches are permitted using the current permissions of +the directory underlying the file descriptor. If the access mode is +O_SEARCH, the function shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_SYMLINK_FOLLOW 6 +.br +If +.IR path1 +names a symbolic link, a new link for the target of the symbolic link +is created. +.P +If +\fIlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd1 +or +.IR fd2 +parameter, the current working directory shall be used for the respective +.IR path +argument. If both +.IR fd1 +and +.IR fd2 +have value AT_FDCWD, the behavior shall be identical to a call to +\fIlink\fR(), +except that symbolic links shall be handled as specified by the value of +.IR flag . +.P +If the AT_SYMLINK_FOLLOW flag is clear in the +.IR flag +argument and the +.IR path1 +argument names a symbolic link, a new link is created for the symbolic +link +.IR path1 +and not its target. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. Otherwise, +these functions shall return \-1 and set +.IR errno +to indicate the error. +.br +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +A component of either path prefix denies search permission, or the +requested link requires writing in a directory that denies write +permission, or the calling process does not have permission to access +the existing file and this is required by the implementation. +.TP +.BR EEXIST +The +.IR path2 +argument resolves to an existing directory entry or refers to a symbolic +link. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path1 +or +.IR path2 +argument. +.TP +.BR EMLINK +The number of links to the file named by +.IR path1 +would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of either path prefix does not exist; the file named by +.IR path1 +does not exist; or +.IR path1 +or +.IR path2 +points to an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path1 +argument names an existing non-directory file, and the +.IR path2 +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path2 +without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory to contain the link cannot be extended. +.TP +.BR ENOTDIR +A component of either path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path1 +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory, or the +.IR path1 +argument names an existing non-directory file and the +.IR path2 +argument names a nonexistent file, contains at least one non-\c + +character, and ends with one or more trailing + +characters. +.TP +.BR EPERM +The file named by +.IR path1 +is a directory and either the calling process does not have appropriate +privileges or the implementation prohibits using +\fIlink\fR() +on directories. +.TP +.BR EROFS +The requested link requires writing in a directory on a read-only file +system. +.TP +.BR EXDEV +The link named by +.IR path2 +and the file named by +.IR path1 +are on different file systems and the implementation does not support +links between file systems. +.TP +.BR EXDEV +.IR path1 +refers to a named STREAM. +.P +The +\fIlinkat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd1 +or +.IR fd2 +is not O_SEARCH and the permissions of the directory underlying +.IR fd1 +or +.IR fd2 , +respectively, do not permit directory searches. +.TP +.BR EBADF +The +.IR path1 +or +.IR path2 +argument does not specify an absolute path and the +.IR fd1 +or +.IR fd2 +argument, respectively, is neither AT_FDCWD nor a valid file descriptor +open for reading or searching. +.TP +.BR ENOTDIR +The +.IR path1 +or +.IR path2 +argument is not an absolute path and +.IR fd1 +or +.IR fd2 , +respectively, is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path1 +or +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.br +.P +The +\fIlinkat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Link to a File" +.P +The following example shows how to create a link to a file named +.BR /home/cnd/mod1 +by creating a new directory entry named +.BR /modules/pass1 . +.sp +.RS 4 +.nf + +#include +.P +char *path1 = "/home/cnd/mod1"; +char *path2 = "/modules/pass1"; +int status; +\&... +status = link (path1, path2); +.fi +.P +.RE +.SS "Creating a Link to a File Within a Program" +.P +In the following program example, the +\fIlink\fR() +function links the +.BR /etc/passwd +file (defined as +.BR PASSWDFILE ) +to a file named +.BR /etc/opasswd +(defined as +.BR SAVEFILE ), +which is used to save the current password file. Then, after removing +the current password file (defined as +.BR PASSWDFILE ), +the new password file is saved as the current password file using the +\fIlink\fR() +function again. +.sp +.RS 4 +.nf + +#include +.P +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +#define SAVEFILE "/etc/opasswd" +\&... +/* Save current password file */ +link (PASSWDFILE, SAVEFILE); +.P +/* Remove current password file. */ +unlink (PASSWDFILE); +.P +/* Save new password file as current password file. */ +link (LOCKFILE,PASSWDFILE); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Some implementations do allow links between file systems. +.P +If +.IR path1 +refers to a symbolic link, application developers should use +\fIlinkat\fR() +with appropriate flags to select whether or not the symbolic link should +be resolved. +.SH RATIONALE +Linking to a directory is restricted to the superuser +in most historical implementations because this capability may produce +loops in the file hierarchy or otherwise corrupt the file system. This volume of POSIX.1\(hy2017 +continues that philosophy by prohibiting +\fIlink\fR() +and +\fIunlink\fR() +from doing this. Other functions could do it if the implementor designed +such an extension. +.P +Some historical implementations allow linking of files on different file +systems. Wording was added to explicitly allow this optional behavior. +.P +The exception for cross-file system links is intended to apply only to +links that are programmatically indistinguishable from ``hard'' links. +.P +The purpose of the +\fIlinkat\fR() +function is to link files in directories other than the current working +directory without exposure to race conditions. Any part of the path of +a file could be changed in parallel to a call to +\fIlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for the +directory of both the existing file and the target location and using the +\fIlinkat\fR() +function it can be guaranteed that the both filenames are in the desired +directories. +.P +The AT_SYMLINK_FOLLOW flag allows for implementing both common behaviors +of the +\fIlink\fR() +function. The POSIX specification requires that if +.IR path1 +is a symbolic link, a new link for the target of the symbolic link is +created. Many systems by default or as an alternative provide a mechanism +to avoid the implicit symbolic link lookup and create a new link for +the symbolic link itself. +.P +Earlier versions of this standard specified only the +\fIlink\fR() +function, and required it to behave like +\fIlinkat\fR() +with the AT_SYMLINK_FOLLOW flag. However, historical practice from SVR4 +and Linux kernels had +\fIlink\fR() +behaving like +\fIlinkat\fR() +with no flags, and many systems that attempted to provide a conforming +\fIlink\fR() +function did so in a way that was rarely used, and when it was used +did not conform to the standard (e.g., by not being atomic, or by +dereferencing the symbolic link incorrectly). Since applications could +not rely on +\fIlink\fR() +following links in practice, the +\fIlinkat\fR() +function was added taking a flag to specify the desired behavior +for the application. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrename\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lio_listio.3p b/upstream/archlinux/man3p/lio_listio.3p new file mode 100644 index 00000000..3621e209 --- /dev/null +++ b/upstream/archlinux/man3p/lio_listio.3p @@ -0,0 +1,356 @@ +'\" et +.TH LIO_LISTIO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lio_listio +\(em list directed I/O +.SH SYNOPSIS +.LP +.nf +#include +.P +int lio_listio(int \fImode\fP, struct aiocb *restrict const \fIlist\fP[restrict], + int \fInent\fP, struct sigevent *restrict \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIlio_listio\fR() +function shall initiate a list of I/O requests with a single +function call. +.P +The +.IR mode +argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in +.IR +and determines whether the function returns when the I/O operations +have been completed, or as soon as the operations have been queued. If +the +.IR mode +argument is LIO_WAIT, the function shall wait until all I/O is +complete and the +.IR sig +argument shall be ignored. +.P +If the +.IR mode +argument is LIO_NOWAIT, the function shall return immediately, and +asynchronous notification shall occur, according to the +.IR sig +argument, when all the I/O operations complete. If +.IR sig +is NULL, then no asynchronous notification shall occur. If +.IR sig +is not NULL, asynchronous notification occurs as specified in +.IR "Section 2.4.1" ", " "Signal Generation and Delivery" +when all the requests in +.IR list +have completed. +.P +The I/O requests enumerated by +.IR list +are submitted in an unspecified order. +.P +The +.IR list +argument is an array of pointers to +.BR aiocb +structures. The array contains +.IR nent +elements. The array may contain NULL elements, which shall be ignored. +.P +If the buffer pointed to by +.IR list +or the +.BR aiocb +structures pointed to by the elements of the array +.IR list +become illegal addresses before all asynchronous I/O completed and, if +necessary, the notification is sent, then the behavior is undefined. If +the buffers pointed to by the +.IR aio_buf +member of the +.BR aiocb +structure pointed to by the elements of the array +.IR list +become illegal addresses prior to the asynchronous I/O associated with +that +.BR aiocb +structure being completed, the behavior is undefined. +.P +The +.IR aio_lio_opcode +field of each +.BR aiocb +structure specifies the operation to be performed. The supported +operations are LIO_READ, LIO_WRITE, and LIO_NOP; +these symbols are defined in +.IR . +The LIO_NOP operation causes the list entry to be ignored. If the +.IR aio_lio_opcode +element is equal to LIO_READ, then an I/O operation is submitted as if +by a call to +\fIaio_read\fR() +with the +.IR aiocbp +equal to the address of the +.BR aiocb +structure. If the +.IR aio_lio_opcode +element is equal to LIO_WRITE, then an I/O operation is submitted as if +by a call to +\fIaio_write\fR() +with the +.IR aiocbp +equal to the address of the +.BR aiocb +structure. +.P +The +.IR aio_fildes +member specifies the file descriptor on which the operation is to be +performed. +.P +The +.IR aio_buf +member specifies the address of the buffer to or from which the data is +transferred. +.P +The +.IR aio_nbytes +member specifies the number of bytes of data to be transferred. +.P +The members of the +.BR aiocb +structure further describe the I/O operation to be performed, in a +manner identical to that of the corresponding +.BR aiocb +structure when used by the +\fIaio_read\fR() +and +\fIaio_write\fR() +functions. +.P +The +.IR nent +argument specifies how many elements are members of the list; that is, +the length of the array. +.P +The behavior of this function is altered according to the definitions +of synchronized I/O data integrity completion and synchronized I/O file +integrity completion if synchronized I/O is enabled on the file +associated with +.IR aio_fildes . +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +\fIaiocbp\fR\->\fIaio_fildes\fR. +.P +If \fIsig\fR\->\fIsigev_notify\fR is SIGEV_THREAD and +\fIsig\fR\->\fIsigev_notify_attributes\fR is a non-null pointer and the +block pointed to by this pointer becomes an illegal address prior to +all asynchronous I/O being completed, then the behavior is undefined. +.SH "RETURN VALUE" +If the +.IR mode +argument has the value LIO_NOWAIT, the +\fIlio_listio\fR() +function shall return the value zero if the I/O operations are +successfully queued; otherwise, the function shall return the value +\-1 and set +.IR errno +to indicate the error. +.P +If the +.IR mode +argument has the value LIO_WAIT, the +\fIlio_listio\fR() +function shall return the value zero when all the indicated I/O has +completed successfully. Otherwise, +\fIlio_listio\fR() +shall return a value of \-1 and set +.IR errno +to indicate the error. +.P +In either case, the return value only indicates the success or failure +of the +\fIlio_listio\fR() +call itself, not the status of the individual I/O requests. In some +cases one or more of the I/O requests contained in the list may fail. +Failure of an individual request does not prevent completion of any +other individual request. To determine the outcome of each I/O +request, the application shall examine the error status associated with +each +.BR aiocb +control block. The error statuses so returned are identical to those +returned as the result of an +\fIaio_read\fR() +or +\fIaio_write\fR() +function. +.SH ERRORS +The +\fIlio_listio\fR() +function shall fail if: +.TP +.BR EAGAIN +The resources necessary to queue all the I/O requests were not +available. The application may check the error status for each +.BR aiocb +to determine the individual request(s) that failed. +.TP +.BR EAGAIN +The number of entries indicated by +.IR nent +would cause the system-wide limit +{AIO_MAX} +to be exceeded. +.TP +.BR EINVAL +The +.IR mode +argument is not a proper value, or the value of +.IR nent +was greater than +{AIO_LISTIO_MAX}. +.TP +.BR EINTR +A signal was delivered while waiting for all I/O requests to complete +during an LIO_WAIT operation. Note that, since each I/O operation +invoked by +\fIlio_listio\fR() +may possibly provoke a signal when it completes, this error return may +be caused by the completion of one (or more) of the very I/O operations +being awaited. Outstanding I/O requests are not canceled, and the +application shall examine each list element to determine whether the +request was initiated, canceled, or completed. +.TP +.BR EIO +One or more of the individual I/O operations failed. The application +may check the error status for each +.BR aiocb +structure to determine the individual request(s) that failed. +.P +In addition to the errors returned by the +\fIlio_listio\fR() +function, if the +\fIlio_listio\fR() +function succeeds or fails with errors of +.BR [EAGAIN] , +.BR [EINTR] , +or +.BR [EIO] , +then some of the I/O specified by the list may have been initiated. If +the +\fIlio_listio\fR() +function fails with an error code other than +.BR [EAGAIN] , +.BR [EINTR] , +or +.BR [EIO] , +no operations from the list shall have been initiated. The I/O operation +indicated by each list element can encounter errors specific to the +individual read or write function being performed. In this event, the +error status for each +.BR aiocb +control block contains the associated error code. The error codes that +can be set are the same as would be set by a +\fIread\fR() +or +\fIwrite\fR() +function, with the following additional error codes possible: +.TP +.BR EAGAIN +The requested I/O operation was not queued due to resource limitations. +.TP +.BR ECANCELED +The requested I/O was canceled before the I/O completed due to an +explicit +\fIaio_cancel\fR() +request. +.TP +.BR EFBIG +The \fIaiocbp\fP\->\fIaio_lio_opcode\fP is LIO_WRITE, the file is a +regular file, \fIaiocbp\fP\->\fIaio_nbytes\fP is greater than 0, and +the \fIaiocbp\fP\->\fIaio_offset\fP is greater than or equal to the +offset maximum in the open file description associated with +\fIaiocbp\fP\->\fIaio_fildes\fP. +.TP +.BR EINPROGRESS +The requested I/O is in progress. +.TP +.BR EOVERFLOW +The \fIaiocbp\fP\->\fIaio_lio_opcode\fP is LIO_READ, the file is a +regular file, \fIaiocbp\fP\->\fIaio_nbytes\fP is greater than 0, and +the \fIaiocbp\fP\->\fIaio_offset\fP is before the end-of-file and is +greater than or equal to the offset maximum in the open file +description associated with \fIaiocbp\fP\->\fIaio_fildes\fP. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Although it may appear that there are inconsistencies in the specified +circumstances for error codes, the +.BR [EIO] +error condition applies when any circumstance relating to an individual +operation makes that operation fail. This might be due to a badly +formulated request (for example, the +.IR aio_lio_opcode +field is invalid, and +\fIaio_error\fR() +returns +.BR [EINVAL] ) +or might arise from application behavior (for example, the file +descriptor is closed before the operation is initiated, and +\fIaio_error\fR() +returns +.BR [EBADF] ). +.P +The limitation on the set of error codes returned when operations from +the list shall have been initiated enables applications to know when +operations have been started and whether +\fIaio_error\fR() +is valid for a specific operation. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaio_read\fR\^(\|)", +.IR "\fIaio_write\fR\^(\|)", +.IR "\fIaio_error\fR\^(\|)", +.IR "\fIaio_return\fR\^(\|)", +.IR "\fIaio_cancel\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIread\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/listen.3p b/upstream/archlinux/man3p/listen.3p new file mode 100644 index 00000000..6eada99b --- /dev/null +++ b/upstream/archlinux/man3p/listen.3p @@ -0,0 +1,155 @@ +'\" et +.TH LISTEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +listen +\(em listen for socket connections and limit the queue of incoming +connections +.SH SYNOPSIS +.LP +.nf +#include +.P +int listen(int \fIsocket\fP, int \fIbacklog\fP); +.fi +.SH DESCRIPTION +The +\fIlisten\fR() +function shall mark a connection-mode socket, specified by the +.IR socket +argument, as accepting connections. +.P +The +.IR backlog +argument provides a hint to the implementation which the implementation +shall use to limit the number of outstanding connections in the +socket's listen queue. Implementations may impose a limit on +.IR backlog +and silently reduce the specified value. Normally, a larger +.IR backlog +argument value shall result in a larger or equal length of the listen +queue. Implementations shall support values of +.IR backlog +up to SOMAXCONN, defined in +.IR . +.P +The implementation may include incomplete connections in its listen +queue. The limits on the number of incomplete connections and completed +connections queued may be different. +.P +The implementation may have an upper limit on the length of the listen +queue\(emeither global or per accepting socket. If +.IR backlog +exceeds this limit, the length of the listen queue is set to the +limit. +.P +If +\fIlisten\fR() +is called with a +.IR backlog +argument value that is less than 0, the function behaves as if it had +been called with a +.IR backlog +argument value of 0. +.P +A +.IR backlog +argument of 0 may allow the socket to accept connections, in which case +the length of the listen queue may be set to an +implementation-defined minimum value. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIlisten\fR() +function. +.SH "RETURN VALUE" +Upon successful completions, +\fIlisten\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIlisten\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EDESTADDRREQ +.br +The socket is not bound to a local address, and the protocol does not +support listening on an unbound socket. +.TP +.BR EINVAL +The +.IR socket +is already connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The socket protocol does not support +\fIlisten\fR(). +.P +The +\fIlisten\fR() +function may fail if: +.TP +.BR EACCES +The calling process does not have appropriate privileges. +.TP +.BR EINVAL +The +.IR socket +has been shut down. +.TP +.BR ENOBUFS +Insufficient resources are available in the system to complete the +call. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/llabs.3p b/upstream/archlinux/man3p/llabs.3p new file mode 100644 index 00000000..ab382bad --- /dev/null +++ b/upstream/archlinux/man3p/llabs.3p @@ -0,0 +1,40 @@ +'\" et +.TH LLABS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +llabs +\(em return a long integer absolute value +.SH SYNOPSIS +.LP +.nf +#include +.P +long long llabs(long long \fIi\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlabs\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lldiv.3p b/upstream/archlinux/man3p/lldiv.3p new file mode 100644 index 00000000..3811ef70 --- /dev/null +++ b/upstream/archlinux/man3p/lldiv.3p @@ -0,0 +1,40 @@ +'\" et +.TH LLDIV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lldiv +\(em compute quotient and remainder of a long division +.SH SYNOPSIS +.LP +.nf +#include +.P +lldiv_t lldiv(long long \fInumer\fP, long long \fIdenom\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIldiv\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/llrint.3p b/upstream/archlinux/man3p/llrint.3p new file mode 100644 index 00000000..ae2ab480 --- /dev/null +++ b/upstream/archlinux/man3p/llrint.3p @@ -0,0 +1,149 @@ +'\" et +.TH LLRINT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +llrint, +llrintf, +llrintl +\(em round to the nearest integer value using current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +long long llrint(double \fIx\fP); +long long llrintf(float \fIx\fP); +long long llrintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding according to the current rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur, and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \-Inf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, +a domain error shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, +a domain error shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions provide floating-to-integer conversions. They round +according to the current rounding direction. If the rounded value is +outside the range of the return type, the numeric result is unspecified +and the invalid floating-point exception is raised. When they raise no +other floating-point exception and the result differs from the +argument, they raise the inexact floating-point exception. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlrint\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/llround.3p b/upstream/archlinux/man3p/llround.3p new file mode 100644 index 00000000..b7c93aa9 --- /dev/null +++ b/upstream/archlinux/man3p/llround.3p @@ -0,0 +1,151 @@ +'\" et +.TH LLROUND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +llround, +llroundf, +llroundl +\(em round to nearest integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +long long llround(double \fIx\fP); +long long llroundf(float \fIx\fP); +long long llroundl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding halfway cases away from zero, regardless of the current +rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur, and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \-Inf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR "long long" , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions differ from the +\fIllrint\fR() +functions in that the default rounding direction for the +\fIllround\fR() +functions round halfway cases away from zero and need not raise the +inexact floating-point exception for non-integer arguments that round +to within the range of the return type. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlround\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/localeconv.3p b/upstream/archlinux/man3p/localeconv.3p new file mode 100644 index 00000000..3809f24d --- /dev/null +++ b/upstream/archlinux/man3p/localeconv.3p @@ -0,0 +1,367 @@ +'\" et +.TH LOCALECONV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +localeconv +\(em return locale-specific information +.SH SYNOPSIS +.LP +.nf +#include +.P +struct lconv *localeconv(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIlocaleconv\fR() +function shall set the components of an object with the type +.BR "struct lconv" +with the values appropriate for the formatting of numeric quantities +(monetary and otherwise) according to the rules of the current locale. +.P +The members of the structure with type +.BR "char *" +are pointers to strings, any of which (except +.BR decimal_point ) +can point to +.BR \(dq\^\(dq , +to indicate that the value is not available in the current locale or is +of zero length. The members with type +.BR char +are non-negative numbers, any of which can be +{CHAR_MAX} +to indicate that the value is not available in the current locale. +.P +The members include the following: +.IP "\fBchar\ *decimal_point\fP" 6 +.br +The radix character used to format non-monetary quantities. +.IP "\fBchar\ *thousands_sep\fP" 6 +.br +The character used to separate groups of digits before the +decimal-point character in formatted non-monetary quantities. +.IP "\fBchar\ *grouping\fP" 6 +.br +A string whose elements taken as one-byte integer values indicate the +size of each group of digits in formatted non-monetary quantities. +.IP "\fBchar\ *int_curr_symbol\fP" 6 +.br +The international currency symbol applicable to the current locale. +The first three characters contain the alphabetic international +currency symbol in accordance with those specified in the ISO\ 4217:\|2001 standard. The +fourth character (immediately preceding the null byte) is the character +used to separate the international currency symbol from the monetary +quantity. +.IP "\fBchar\ *currency_symbol\fP" 6 +.br +The local currency symbol applicable to the current locale. +.IP "\fBchar\ *mon_decimal_point\fP" 6 +.br +The radix character used to format monetary quantities. +.IP "\fBchar\ *mon_thousands_sep\fP" 6 +.br +The separator for groups of digits before the decimal-point in +formatted monetary quantities. +.IP "\fBchar\ *mon_grouping\fP" 6 +.br +A string whose elements taken as one-byte integer values indicate the +size of each group of digits in formatted monetary quantities. +.IP "\fBchar\ *positive_sign\fP" 6 +.br +The string used to indicate a non-negative valued formatted monetary +quantity. +.IP "\fBchar\ *negative_sign\fP" 6 +.br +The string used to indicate a negative valued formatted monetary +quantity. +.IP "\fBchar\ int_frac_digits\fP" 6 +.br +The number of fractional digits (those after the decimal-point) to be +displayed in an internationally formatted monetary quantity. +.IP "\fBchar\ frac_digits\fP" 6 +.br +The number of fractional digits (those after the decimal-point) to be +displayed in a formatted monetary quantity. +.IP "\fBchar\ p_cs_precedes\fP" 6 +.br +Set to 1 if the +.BR currency_symbol +precedes the value for a non-negative formatted monetary quantity. Set +to 0 if the symbol succeeds the value. +.IP "\fBchar\ p_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR currency_symbol , +the sign string, and the value for a non-negative formatted monetary +quantity. +.IP "\fBchar\ n_cs_precedes\fP" 6 +.br +Set to 1 if the +.BR currency_symbol +precedes the value for a negative formatted monetary quantity. Set +to 0 if the symbol succeeds the value. +.IP "\fBchar\ n_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR currency_symbol , +the sign string, and the value for a negative formatted monetary +quantity. +.IP "\fBchar\ p_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR positive_sign +for a non-negative formatted monetary quantity. +.IP "\fBchar\ n_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR negative_sign +for a negative formatted monetary quantity. +.IP "\fBchar\ int_p_cs_precedes\fP" 6 +.br +Set to 1 or 0 if the +.BR int_curr_symbol +respectively precedes or succeeds the value for a non-negative +internationally formatted monetary quantity. +.IP "\fBchar\ int_n_cs_precedes\fP" 6 +.br +Set to 1 or 0 if the +.BR int_curr_symbol +respectively precedes or succeeds the value for a negative +internationally formatted monetary quantity. +.IP "\fBchar\ int_p_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR int_curr_symbol , +the sign string, and the value for a non-negative internationally +formatted monetary quantity. +.IP "\fBchar\ int_n_sep_by_space\fP" 6 +.br +Set to a value indicating the separation of the +.BR int_curr_symbol , +the sign string, and the value for a negative internationally formatted +monetary quantity. +.IP "\fBchar\ int_p_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR positive_sign +for a non-negative internationally formatted monetary quantity. +.IP "\fBchar\ int_n_sign_posn\fP" 6 +.br +Set to a value indicating the positioning of the +.BR negative_sign +for a negative internationally formatted monetary quantity. +.P +The elements of +.BR grouping +and +.BR mon_grouping +are interpreted according to the following: +.IP {CHAR_MAX} 12 +No further grouping is to be performed. +.IP 0 12 +The previous element is to be repeatedly used for the remainder of the +digits. +.IP "\fIother\fP" 12 +The integer value is the number of digits that comprise the current +group. The next element is examined to determine the size of the next +group of digits before the current group. +.P +The values of +.BR p_sep_by_space , +.BR n_sep_by_space , +.BR int_p_sep_by_space , +and +.BR int_n_sep_by_space +are interpreted according to the following: +.IP 0 6 +No space separates the currency symbol and value. +.IP 1 6 +If the currency symbol and sign string are adjacent, a space separates +them from the value; otherwise, a space separates the currency symbol +from the value. +.IP 2 6 +If the currency symbol and sign string are adjacent, a space separates +them; otherwise, a space separates the sign string from the value. +.P +For +.BR int_p_sep_by_space +and +.BR int_n_sep_by_space , +the fourth character of +.BR int_curr_symbol +is used instead of a space. +.P +The values of +.BR p_sign_posn , +.BR n_sign_posn , +.BR int_p_sign_posn , +and +.BR int_n_sign_posn +are interpreted according to the following: +.IP 0 6 +Parentheses surround the quantity and +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 1 6 +The sign string precedes the quantity and +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 2 6 +The sign string succeeds the quantity and +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 3 6 +The sign string immediately precedes the +.BR currency_symbol +or +.BR int_curr_symbol . +.IP 4 6 +The sign string immediately succeeds the +.BR currency_symbol +or +.BR int_curr_symbol . +.P +The implementation shall behave as if no function in this volume of POSIX.1\(hy2017 calls +\fIlocaleconv\fR(). +.P +The +\fIlocaleconv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fIlocaleconv\fR() +function shall return a pointer to the filled-in object. The application +shall not modify the structure to which the return value points, +nor any storage areas pointed to by pointers within the structure. The +returned pointer, and pointers within the structure, might be +invalidated or +the structure +or the storage areas +might be overwritten by a subsequent call to +\fIlocaleconv\fR(). +In addition, +the returned pointer, and pointers within the structure, might be +invalidated or +the structure +or the storage areas +might be overwritten by subsequent calls to +\fIsetlocale\fR() +with the categories LC_ALL, LC_MONETARY, or LC_NUMERIC, +or by calls to +\fIuselocale\fR() +which change the categories LC_MONETARY or LC_NUMERIC. The returned +pointer, pointers within the structure, the structure, and the +storage areas might also be invalidated if the calling thread is +terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The following table illustrates the rules which may be used by four +countries to format monetary quantities. +.TS +center box tab(!); +cB | cB | cB | cB +l | l | l | l. +Country!Positive Format!Negative Format!International Format +_ +Italy!\(eu.1.230!\-\(eu.1.230!EUR.1.230 +Netherlands!\(eu 1.234,56!\(eu \-1.234,56!EUR 1.234,56 +Norway!kr1.234,56!kr1.234,56\-!NOK 1.234,56 +Switzerland!SFrs.1,234.56!SFrs.1,234.56C!CHF 1,234.56 +.TE +.P +For these four countries, the respective values for the monetary +members of the structure returned by +\fIlocaleconv\fR() +are: +.TS +center box tab(!); +cB | cB | cB | cB | cB +lb | cf5 | cf5 | cf5 | cf5. +!Italy!Netherlands!Norway!Switzerland +_ +int_curr_symbol!"EUR."!"EUR "!"NOK "!"CHF " +currency_symbol!"\(eu."!"\(eu"!"kr"!"SFrs." +mon_decimal_point!""!","!","!"." +mon_thousands_sep!"."!"."!"."!"," +mon_grouping!"\e3"!"\e3"!"\e3"!"\e3" +positive_sign!""!""!""!"" +negative_sign!"-"!"-"!"-"!"C" +int_frac_digits!0!2!2!2 +frac_digits!0!2!2!2 +p_cs_precedes!1!1!1!1 +p_sep_by_space!0!1!0!0 +n_cs_precedes!1!1!1!1 +n_sep_by_space!0!1!0!0 +p_sign_posn!1!1!1!1 +n_sign_posn!1!4!2!2 +int_p_cs_precedes!1!1!1!1 +int_n_cs_precedes!1!1!1!1 +int_p_sep_by_space!0!0!0!0 +int_n_sep_by_space!0!0!0!0 +int_p_sign_posn!1!1!1!1 +int_n_sign_posn!1!4!4!2 +.TE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisascii\fR\^(\|)", +.IR "\fInl_langinfo\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrcat\fR\^(\|)", +.IR "\fIstrchr\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)", +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrlen\fR\^(\|)", +.IR "\fIstrpbrk\fR\^(\|)", +.IR "\fIstrspn\fR\^(\|)", +.IR "\fIstrtok\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/localtime.3p b/upstream/archlinux/man3p/localtime.3p new file mode 100644 index 00000000..2a73d069 --- /dev/null +++ b/upstream/archlinux/man3p/localtime.3p @@ -0,0 +1,286 @@ +'\" et +.TH LOCALTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +localtime, +localtime_r +\(em convert a time value to a broken-down local time +.SH SYNOPSIS +.LP +.nf +#include +.P +struct tm *localtime(const time_t *\fItimer\fP); +struct tm *localtime_r(const time_t *restrict \fItimer\fP, + struct tm *restrict \fIresult\fP); +.fi +.SH DESCRIPTION +For +\fIlocaltime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIlocaltime\fR() +function shall convert the time in seconds since the Epoch pointed +to by +.IR timer +into a broken-down time, expressed as a local time. The function +corrects for the timezone and any seasonal time adjustments. +Local timezone information is used as though +\fIlocaltime\fR() +calls +\fItzset\fR(). +.P +The relationship between a time in seconds since the Epoch used as an +argument to +\fIlocaltime\fR() +and the +.BR tm +structure (defined in the +.IR +header) is that the result shall be as specified in the expression +given in the definition of seconds since the Epoch (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.16" ", " "Seconds Since the Epoch") +corrected for timezone and any seasonal time adjustments, where the +names in the structure and in the expression correspond. +.P +The same relationship shall apply for +\fIlocaltime_r\fR(). +.P +The +\fIlocaltime\fR() +function need not be thread-safe. +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of type +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIlocaltime_r\fR() +function shall convert the time in seconds since the Epoch pointed +to by +.IR timer +into a broken-down time stored in the structure to which +.IR result +points. The +\fIlocaltime_r\fR() +function shall also return a pointer to that same structure. +.P +Unlike +\fIlocaltime\fR(), +the +\fIlocaltime_r\fR() +function is not required to set +.IR tzname . +If +\fIlocaltime_r\fR() +sets +.IR tzname , +it shall also set +.IR daylight +and +.IR timezone . +If +\fIlocaltime_r\fR() +does not set +.IR tzname , +it shall not set +.IR daylight +and shall not set +.IR timezone . +.SH "RETURN VALUE" +Upon successful completion, the +\fIlocaltime\fR() +function shall return a pointer to the broken-down time structure. +If an error is detected, +\fIlocaltime\fR() +shall return a null pointer +and set +.IR errno +to indicate the error. +.P +Upon successful completion, +\fIlocaltime_r\fR() +shall return a pointer to the structure pointed to by the argument +.IR result . +If an error is detected, +\fIlocaltime_r\fR() +shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIlocaltime\fR() +and +\fIlocaltime_r\fR() +functions shall fail if: +.TP +.BR EOVERFLOW +The result cannot be represented. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Local Date and Time" +.P +The following example uses the +\fItime\fR() +function to calculate the time elapsed, in seconds, since January 1, +1970 0:00 UTC (the Epoch), +\fIlocaltime\fR() +to convert that value to a broken-down time, and +\fIasctime\fR() +to convert the broken-down time values into a printable string. +.sp +.RS 4 +.nf + +#include +#include +.P +int main(void) +{ + time_t result; +.P + result = time(NULL); + printf("%s%ju secs since the Epoch\en", + asctime(localtime(&result)), + (uintmax_t)result); + return(0); +} +.fi +.P +.RE +.P +This example writes the current time to +.IR stdout +in a form like this: +.sp +.RS 4 +.nf + +Wed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +.fi +.P +.RE +.SS "Getting the Modification Time for a File" +.P +The following example prints the last data modification timestamp +in the local timezone for a given file. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +int +print_file_time(const char *pathname) +{ + struct stat statbuf; + struct tm *tm; + char timestr[BUFSIZ]; +.P + if(stat(pathname, &statbuf) =\|= -1) + return -1; + if((tm = localtime(&statbuf.st_mtime)) =\|= NULL) + return -1; + if(strftime(timestr, sizeof(timestr), "%Y-%m-%d %H:%M:%S", tm) =\|= 0) + return -1; + printf("%s: %s.%09ld\en", pathname, timestr, statbuf.st_mtim.tv_nsec); + return 0; +} +.fi +.P +.RE +.SS "Timing an Event" +.P +The following example gets the current time, converts it to a string +using +\fIlocaltime\fR() +and +\fIasctime\fR(), +and prints it to standard output using +\fIfputs\fR(). +It then prints the number of minutes to an event being timed. +.sp +.RS 4 +.nf + +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +fputs(asctime(localtime(&now)), stdout); +printf("There are still %d minutes to the event.\en", + minutes_to_event); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIlocaltime_r\fR() +function is thread-safe and returns values in a user-supplied buffer +instead of possibly using a static data area that may be overwritten by +each call. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgetdate\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.16" ", " "Seconds Since the Epoch", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lockf.3p b/upstream/archlinux/man3p/lockf.3p new file mode 100644 index 00000000..b64216e7 --- /dev/null +++ b/upstream/archlinux/man3p/lockf.3p @@ -0,0 +1,293 @@ +'\" et +.TH LOCKF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lockf +\(em record locking on files +.SH SYNOPSIS +.LP +.nf +#include +.P +int lockf(int \fIfildes\fP, int \fIfunction\fP, off_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIlockf\fR() +function shall lock sections of a file with advisory-mode locks. Calls +to +\fIlockf\fR() +from threads in other processes which attempt to lock the locked file +section shall either return an error value or block until the section +becomes unlocked. All the locks for a process are removed when the +process terminates. Record locking with +\fIlockf\fR() +shall be supported for regular files and may be supported for other +files. +.P +The +.IR fildes +argument is an open file descriptor. To establish a lock with this +function, the file descriptor shall be opened with write-only +permission (O_WRONLY) or with read/write permission (O_RDWR). +.P +The +.IR function +argument is a control value which specifies the action to be taken. The +permissible values for +.IR function +are defined in +.IR +as follows: +.TS +box tab(!) center; +cB | cB +l | l. +Function!Description +_ +F_ULOCK!Unlock locked sections. +F_LOCK!Lock a section for exclusive use. +F_TLOCK!Test and lock a section for exclusive use. +F_TEST!Test a section for locks by other processes. +.TE +.P +F_TEST shall detect if a lock by another process is present on the +specified section. +.P +F_LOCK and F_TLOCK shall both lock a section of a file if the section +is available. +.P +F_ULOCK shall remove locks from a section of the file. +.P +The +.IR size +argument is the number of contiguous bytes to be locked or unlocked. +The section to be locked or unlocked starts at the current offset in +the file and extends forward for a positive size or backward for a +negative size (the preceding bytes up to but not including the current +offset). If +.IR size +is 0, the section from the current offset through the largest possible +file offset shall be locked (that is, from the current offset through +the present or any future end-of-file). An area need not be allocated +to the file to be locked because locks may exist past the end-of-file. +.P +The sections locked with F_LOCK or F_TLOCK may, in whole or in part, +contain or be contained by a previously locked section for the same +process. When this occurs, or if adjacent locked sections would occur, +the sections shall be combined into a single locked section. If the +request would cause the number of locks to exceed a system-imposed +limit, the request shall fail. +.P +F_LOCK and F_TLOCK requests differ only by the action taken if the +section is not available. F_LOCK shall block the calling thread until +the section is available. F_TLOCK shall cause the function to fail if +the section is already locked by another process. +.P +File locks shall be released on first close by the locking process of +any file descriptor for the file. +.P +F_ULOCK requests may release (wholly or in part) one or more locked +sections controlled by the process. Locked sections shall be unlocked +starting at the current file offset through +.IR size +bytes or to the end-of-file if +.IR size +is (\fBoff_t\fR)0. When all of a locked section is not released (that +is, when the beginning or end of the area to be unlocked falls within a +locked section), the remaining portions of that section shall remain +locked by the process. Releasing the center portion of a locked section +shall cause the remaining locked beginning and end portions to become two +separate locked sections. If the request would cause the number of +locks in the system to exceed a system-imposed limit, the request +shall fail. +.P +A potential for deadlock occurs if the threads of a process controlling +a locked section are blocked by accessing a locked section of +another process. If the system detects that deadlock would occur, +\fIlockf\fR() +shall fail with an +.BR [EDEADLK] +error. +.P +The interaction between +\fIfcntl\fR() +and +\fIlockf\fR() +locks is unspecified. +.P +Blocking on a section shall be interrupted by any signal. +.P +An F_ULOCK request in which +.IR size +is non-zero and the offset of the last byte of the requested section is +the maximum value for an object of type +.BR off_t , +when the process has an existing lock in which +.IR size +is 0 and which includes the last byte of the requested section, shall be +treated as a request to unlock from the start of the requested section +with a size equal to 0. Otherwise, an F_ULOCK request shall attempt to +unlock only the requested section. +.P +Attempting to lock a section of a file that is associated with a +buffered stream produces unspecified results. +.SH "RETURN VALUE" +Upon successful completion, +\fIlockf\fR() +shall return 0. Otherwise, it shall return \-1, set +.IR errno +to indicate an error, and existing locks shall not be changed. +.SH ERRORS +The +\fIlockf\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor; or +.IR function +is F_LOCK or F_TLOCK and +.IR fildes +is not a valid file descriptor open for writing. +.TP +.BR EACCES " or " EAGAIN +.br +The +.IR function +argument is F_TLOCK or F_TEST and the section is already locked by +another process. +.TP +.BR EDEADLK +The +.IR function +argument is F_LOCK and a deadlock is detected. +.TP +.BR EINTR +A signal was caught during execution of the function. +.TP +.BR EINVAL +The +.IR function +argument is not one of F_LOCK, F_TLOCK, F_TEST, or F_ULOCK; or +.IR size +plus the current file offset is less than 0. +.TP +.BR EOVERFLOW +The offset of the first, or if +.IR size +is not 0 then the last, byte in the requested section cannot be +represented correctly in an object of type +.BR off_t . +.P +The +\fIlockf\fR() +function may fail if: +.TP +.BR EAGAIN +The +.IR function +argument is F_LOCK or F_TLOCK and the file is mapped with +\fImmap\fR(). +.TP +.BR EDEADLK " or " ENOLCK +.br +The +.IR function +argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request would cause +the number of locks to exceed a system-imposed limit. +.TP +.BR EOPNOTSUPP " or " EINVAL +.br +The implementation does not support the locking of files of the type +indicated by the +.IR fildes +argument. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Locking a Portion of a File" +.P +In the following example, a file named +.BR /home/cnd/mod1 +is being modified. Other processes that use locking are prevented from +changing it during this process. Only the first 10\|000 bytes are +locked, and the lock call fails if another process has any part of this +area locked already. +.sp +.RS 4 +.nf + +#include +#include +.P +int fildes; +int status; +\&... +fildes = open("/home/cnd/mod1", O_RDWR); +status = lockf(fildes, F_TLOCK, (off_t)10000); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Record-locking should not be used in combination with the +\fIfopen\fR(), +\fIfread\fR(), +\fIfwrite\fR(), +and other +.IR stdio +functions. Instead, the more primitive, non-buffered functions (such as +\fIopen\fR()) +should be used. Unexpected results may occur in processes that do +buffering in the user address space. The process may later read/write +data which is/was locked. The +.IR stdio +functions are the most common source of unexpected buffering. +.P +The +\fIalarm\fR() +function may be used to provide a timeout facility in applications +requiring it. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/log.3p b/upstream/archlinux/man3p/log.3p new file mode 100644 index 00000000..72d52638 --- /dev/null +++ b/upstream/archlinux/man3p/log.3p @@ -0,0 +1,153 @@ +'\" et +.TH LOG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +log, +logf, +logl +\(em natural logarithm function +.SH SYNOPSIS +.LP +.nf +#include +.P +double log(double \fIx\fP); +float logf(float \fIx\fP); +long double logl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the natural logarithm of their argument +.IR x , +log\d\s-3\fIe\fR\s+3\u(\fIx\fR). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the natural +logarithm of +.IR x . +.P +If +.IR x +is \(+-0, a pole error shall occur and +\fIlog\fR(), +\fIlogf\fR(), +and +\fIlogl\fR() +shall return \-HUGE_VAL, \-HUGE_VALF, and \-HUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \-Inf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is negative, +or +.IR x +is \-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog10\fR\^(\|)", +.IR "\fIlog1p\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/log10.3p b/upstream/archlinux/man3p/log10.3p new file mode 100644 index 00000000..bc04737e --- /dev/null +++ b/upstream/archlinux/man3p/log10.3p @@ -0,0 +1,151 @@ +'\" et +.TH LOG10 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +log10, +log10f, +log10l +\(em base 10 logarithm function +.SH SYNOPSIS +.LP +.nf +#include +.P +double log10(double \fIx\fP); +float log10f(float \fIx\fP); +long double log10l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the base 10 logarithm of their argument +.IR x , +log\d\s-310\s+3\u(\fIx\fR). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the base 10 +logarithm of +.IR x . +.P +If +.IR x +is \(+-0, a pole error shall occur and +\fIlog10\fR(), +\fIlog10f\fR(), +and +\fIlog10l\fR() +shall return \-HUGE_VAL, \-HUGE_VALF, and \-HUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \-Inf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1, +0 shall be returned. +.P +If +.IR x +is +Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is negative, +or +.IR x +is \-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.P +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIlog\fR\^(\|)", +.IR "\fIpow\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/log1p.3p b/upstream/archlinux/man3p/log1p.3p new file mode 100644 index 00000000..e892c67e --- /dev/null +++ b/upstream/archlinux/man3p/log1p.3p @@ -0,0 +1,179 @@ +'\" et +.TH LOG1P "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +log1p, +log1pf, +log1pl +\(em compute a natural logarithm +.SH SYNOPSIS +.LP +.nf +#include +.P +double log1p(double \fIx\fP); +float log1pf(float \fIx\fP); +long double log1pl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute log\d\s-3e\s+3\u(1.0 + \fIx\fP). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the natural +logarithm of 1.0 + +.IR x . +.P +If +.IR x +is \-1, a pole error shall occur and +\fIlog1p\fR(), +\fIlog1pf\fR(), +and +\fIlog1pl\fR() +shall return \-HUGE_VAL, \-HUGE_VALF, and \-HUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than \-1, +or if +.IR x +is \-Inf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, or +Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIlog1p\fR(), +\fIlog1pf\fR(), +and +\fIlog1pl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is less than \-1, +or +.IR x +is \-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is \-1. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/log2.3p b/upstream/archlinux/man3p/log2.3p new file mode 100644 index 00000000..de8c72e2 --- /dev/null +++ b/upstream/archlinux/man3p/log2.3p @@ -0,0 +1,150 @@ +'\" et +.TH LOG2 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +log2, +log2f, +log2l +\(em compute base 2 logarithm functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double log2(double \fIx\fP); +float log2f(float \fIx\fP); +long double log2l(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the base 2 logarithm of their argument +.IR x , +log\s-3\d2\u\s+3(\fIx\fR). +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the base 2 +logarithm of +.IR x . +.P +If +.IR x +is \(+-0, a pole error shall occur and +\fIlog2\fR(), +\fIlog2f\fR(), +and +\fIlog2l\fR() +shall return \-HUGE_VAL, \-HUGE_VALF, and \-HUGE_VALL, +respectively. +.P +For finite values of +.IR x +that are less than 0, +or if +.IR x +is \-Inf, +a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is 1, +0 shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is less than zero, +or +.IR x +is \-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlog\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/logb.3p b/upstream/archlinux/man3p/logb.3p new file mode 100644 index 00000000..1f1b4de5 --- /dev/null +++ b/upstream/archlinux/man3p/logb.3p @@ -0,0 +1,165 @@ +'\" et +.TH LOGB "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +logb, +logbf, +logbl +\(em radix-independent exponent +.SH SYNOPSIS +.LP +.nf +#include +.P +double logb(double \fIx\fP); +float logbf(float \fIx\fP); +long double logbl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the exponent of +.IR x , +which is the integral part of log\fI\d\s-3r\s+3\u\fR +|\|\fIx\fR\||, as a signed floating-point value, for non-zero +.IR x , +where +.IR r +is the radix of the machine's floating-point arithmetic, which is the +value of FLT_RADIX defined in the +.IR +header. +.P +If +.IR x +is subnormal it is treated as though it were normalized; thus for +finite positive +.IR x : +.sp +.RS 4 +.nf + +1 <= \fIx\fP * FLT_RADIX\s-3\u-logb(x)\d\s+3 < FLT_RADIX +.fi +.P +.RE +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the exponent +of +.IR x . +.P +If +.IR x +is \(+-0, +\fIlogb\fR(), +\fIlogbf\fR(), +and +\fIlogbl\fR() +shall return \-HUGE_VAL, \-HUGE_VALF, and \-HUGE_VALL, +respectively. +.P +On systems that support the IEC 60559 Floating-Point option, a pole +error shall occur; +.br +otherwise, a +pole +error may occur. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-Inf, +Inf shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Pole\ Error" 12 +The value of +.IR x +is \(+-0. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.P +These functions may fail if: +.IP "Pole\ Error" 12 +The value of +.IR x +is 0. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIilogb\fR\^(\|)", +.IR "\fIscalbln\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/logf.3p b/upstream/archlinux/man3p/logf.3p new file mode 100644 index 00000000..7ebf1381 --- /dev/null +++ b/upstream/archlinux/man3p/logf.3p @@ -0,0 +1,42 @@ +'\" et +.TH LOGF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +logf, +logl +\(em natural logarithm function +.SH SYNOPSIS +.LP +.nf +#include +.P +float logf(float \fIx\fP); +long double logl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlog\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/longjmp.3p b/upstream/archlinux/man3p/longjmp.3p new file mode 100644 index 00000000..816d9b8e --- /dev/null +++ b/upstream/archlinux/man3p/longjmp.3p @@ -0,0 +1,176 @@ +'\" et +.TH LONGJMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +longjmp +\(em non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +void longjmp(jmp_buf \fIenv\fP, int \fIval\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIlongjmp\fR() +function shall restore the environment saved by the most recent +invocation of +\fIsetjmp\fR() +in the same process, with the corresponding +.BR jmp_buf +argument. If the most recent invocation of +\fIsetjmp\fR() +with the corresponding +.BR jmp_buf +occurred in another thread, or if there is no such invocation, or if +the function containing the invocation of +\fIsetjmp\fR() +has terminated execution in the interim, or if the invocation of +\fIsetjmp\fR() +was within the scope of an identifier with variably modified type and +execution has left that scope in the interim, the behavior is undefined. +It is unspecified whether +\fIlongjmp\fR() +restores the signal mask, leaves the signal mask unchanged, or restores +it to its value at the time +\fIsetjmp\fR() +was called. +.P +All accessible objects have values, and all other components of the +abstract machine have state (for example, floating-point status flags +and open files), as of the time +\fIlongjmp\fR() +was called, except that the values of objects of automatic storage +duration are unspecified if they meet all the following conditions: +.IP " *" 4 +They are local to the function containing the corresponding +\fIsetjmp\fR() +invocation. +.IP " *" 4 +They do not have volatile-qualified type. +.IP " *" 4 +They are changed between the +\fIsetjmp\fR() +invocation and +\fIlongjmp\fR() +call. +.P +Although +\fIlongjmp\fR() +is an async-signal-safe function, if it is invoked from a signal +handler which interrupted a non-async-signal-safe function or +equivalent (such as the processing equivalent to +\fIexit\fR() +performed after a return from the initial call to +\fImain\fR()), +the behavior of any subsequent call to a non-async-signal-safe +function or equivalent is undefined. +.P +The effect of a call to +\fIlongjmp\fR() +where initialization of the +.BR jmp_buf +structure was not performed in the calling thread is undefined. +.SH "RETURN VALUE" +After +\fIlongjmp\fR() +is completed, program execution continues as if the corresponding +invocation of +\fIsetjmp\fR() +had just returned the value specified by +.IR val . +The +\fIlongjmp\fR() +function shall not cause +\fIsetjmp\fR() +to return 0; if +.IR val +is 0, +\fIsetjmp\fR() +shall return 1. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications whose behavior depends on the value of the signal mask +should not use +\fIlongjmp\fR() +and +\fIsetjmp\fR(), +since their effect on the signal mask is unspecified, but should +instead use the +\fIsiglongjmp\fR() +and +\fIsigsetjmp\fR() +functions (which can save and restore the signal mask under application +control). +.P +It is recommended that applications do not call +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +from signal handlers. To avoid undefined behavior when calling these +functions from a signal handler, the application needs to ensure one +of the following two things: +.IP " 1." 4 +After the call to +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +the process only calls async-signal-safe functions and does not return +from the initial call to +\fImain\fR(). +.IP " 2." 4 +Any signal whose handler calls +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +is blocked during +.IR every +call to a non-async-signal-safe function, and no such calls are made +after returning from the initial call to +\fImain\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lrand48.3p b/upstream/archlinux/man3p/lrand48.3p new file mode 100644 index 00000000..428c880c --- /dev/null +++ b/upstream/archlinux/man3p/lrand48.3p @@ -0,0 +1,41 @@ +'\" et +.TH LRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lrand48 +\(em generate uniformly distributed pseudo-random non-negative +long integers +.SH SYNOPSIS +.LP +.nf +#include +.P +long lrand48(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lrint.3p b/upstream/archlinux/man3p/lrint.3p new file mode 100644 index 00000000..68f19998 --- /dev/null +++ b/upstream/archlinux/man3p/lrint.3p @@ -0,0 +1,149 @@ +'\" et +.TH LRINT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lrint, +lrintf, +lrintl +\(em round to nearest integer value using current rounding direction +.SH SYNOPSIS +.LP +.nf +#include +.P +long lrint(double \fIx\fP); +long lrintf(float \fIx\fP); +long lrintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding according to the current rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \-Inf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions provide floating-to-integer conversions. They round +according to the current rounding direction. If the rounded value is +outside the range of the return type, the numeric result is unspecified +and the invalid floating-point exception is raised. When they raise no +other floating-point exception and the result differs from the +argument, they raise the inexact floating-point exception. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIllrint\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lround.3p b/upstream/archlinux/man3p/lround.3p new file mode 100644 index 00000000..5426fbdc --- /dev/null +++ b/upstream/archlinux/man3p/lround.3p @@ -0,0 +1,151 @@ +'\" et +.TH LROUND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lround, +lroundf, +lroundl +\(em round to nearest integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +long lround(double \fIx\fP); +long lroundf(float \fIx\fP); +long lroundl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer +value, rounding halfway cases away from zero, regardless of the current +rounding direction. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +.P +If +.IR x +is NaN, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is +Inf, a domain error shall occur and an unspecified value is +returned. +.P +If +.IR x +is \-Inf, a domain error shall occur and an unspecified value is +returned. +.P +If the correct value is positive and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +shall occur; +otherwise, a +domain +error may occur. +.P +If the correct value is negative and too large to represent as a +.BR long , +an unspecified value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +shall occur; +otherwise, a +domain +error may occur. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is NaN or \(+-Inf, or the correct value is not representable +as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The correct value is not representable as an integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions differ from the +\fIlrint\fR() +functions in the default rounding direction, with the +\fIlround\fR() +functions rounding halfway cases away from zero and needing not to +raise the inexact floating-point exception for non-integer arguments +that round to within the range of the return type. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIllround\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lsearch.3p b/upstream/archlinux/man3p/lsearch.3p new file mode 100644 index 00000000..0abc9b1d --- /dev/null +++ b/upstream/archlinux/man3p/lsearch.3p @@ -0,0 +1,156 @@ +'\" et +.TH LSEARCH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lsearch, +lfind +\(em linear search and update +.SH SYNOPSIS +.LP +.nf +#include +.P +void *lsearch(const void *\fIkey\fP, void *\fIbase\fP, size_t *\fInelp\fP, size_t \fIwidth\fP, + int (*\fIcompar\fP)(const void *, const void *)); +void *lfind(const void *\fIkey\fP, const void *\fIbase\fP, size_t *\fInelp\fP, + size_t width, int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +The +\fIlsearch\fR() +function shall linearly search the table and return a pointer into the +table for the matching entry. If the entry does not occur, it shall be +added at the end of the table. The +.IR key +argument points to the entry to be sought in the table. The +.IR base +argument points to the first element in the table. The +.IR width +argument is the size of an element in bytes. The +.IR nelp +argument points to an integer containing the current number of elements +in the table. The integer to which +.IR nelp +points shall be incremented if the entry is added to the table. The +.IR compar +argument points to a comparison function which the application shall +supply (for example, +\fIstrcmp\fR()). +It is called with two arguments that point to the elements being +compared. The application shall ensure that the function returns 0 +if the elements are equal, and non-zero otherwise. +.P +The +\fIlfind\fR() +function shall be equivalent to +\fIlsearch\fR(), +except that if the entry is not found, it is not added to the table. +Instead, a null pointer is returned. +.SH "RETURN VALUE" +If the searched for entry is found, both +\fIlsearch\fR() +and +\fIlfind\fR() +shall return a pointer to it. Otherwise, +\fIlfind\fR() +shall return a null pointer and +\fIlsearch\fR() +shall return a pointer to the newly added element. +.P +Both functions shall return a null pointer in case of error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.SS "Storing Strings in a Table" +.P +This fragment reads in less than or equal to TABSIZE +strings of length less than or equal to ELSIZE and stores them in a +table, eliminating duplicates. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +#define TABSIZE 50 +#define ELSIZE 120 +.P +\&... + char line[ELSIZE], tab[TABSIZE][ELSIZE]; + size_t nel = 0; + ... + while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE) + (void) lsearch(line, tab, &nel, + ELSIZE, (int (*)(const void *, const void *)) strcmp); + ... +.fi +.P +.RE +.SS "Finding a Matching Entry" +.P +The following example finds any line that reads +.BR \(dqThis is a test.\(dq . +.sp +.RS 4 +.nf + +#include +#include +\&... +char line[ELSIZE], tab[TABSIZE][ELSIZE]; +size_t nel = 0; +char *findline; +void *entry; +.P +findline = "This is a test.\en"; +.P +entry = lfind(findline, tab, &nel, ELSIZE, ( + int (*)(const void *, const void *)) strcmp); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The comparison function need not compare every byte, so arbitrary +data may be contained in the elements in addition to the values +being compared. +.P +Undefined results can occur if there is not enough room in the table to +add a new item. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhcreate\fR\^(\|)", +.IR "\fItdelete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lseek.3p b/upstream/archlinux/man3p/lseek.3p new file mode 100644 index 00000000..68e69e0c --- /dev/null +++ b/upstream/archlinux/man3p/lseek.3p @@ -0,0 +1,185 @@ +'\" et +.TH LSEEK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lseek +\(em move the read/write file offset +.SH SYNOPSIS +.LP +.nf +#include +.P +off_t lseek(int \fIfildes\fP, off_t \fIoffset\fP, int \fIwhence\fP); +.fi +.SH DESCRIPTION +The +\fIlseek\fR() +function shall set the file offset for the open file description +associated with the file descriptor +.IR fildes, +as follows: +.IP " *" 4 +If +.IR whence +is SEEK_SET, the file offset shall be set to +.IR offset +bytes. +.IP " *" 4 +If +.IR whence +is SEEK_CUR, the file offset shall be set to its current location plus +.IR offset . +.IP " *" 4 +If +.IR whence +is SEEK_END, the file offset shall be set to the size of the file plus +.IR offset . +.P +The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END +are defined in +.IR . +.P +The behavior of +\fIlseek\fR() +on devices which are incapable of seeking is implementation-defined. +The value of the file offset associated with such a device is +undefined. +.P +The +\fIlseek\fR() +function shall allow the file offset to be set beyond the end of the +existing data in the file. If data is later written at this point, +subsequent reads of data in the gap shall return bytes with the value 0 +until data is actually written into the gap. +.P +The +\fIlseek\fR() +function shall not, by itself, extend the size of a file. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIlseek\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIlseek\fR() +function is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the resulting offset, as measured in bytes +from the beginning of the file, shall be returned. Otherwise, \-1 +shall be returned, +.IR errno +shall be set to indicate the error, and the file offset shall remain +unchanged. +.SH ERRORS +The +\fIlseek\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not an open file descriptor. +.TP +.BR EINVAL +The +.IR whence +argument is not a proper value, or the resulting file offset would be +negative for a regular file, block special file, or directory. +.TP +.BR EOVERFLOW +The resulting file offset would be a value which cannot be represented +correctly in an object of type +.BR off_t . +.TP +.BR ESPIPE +The +.IR fildes +argument is associated with a pipe, FIFO, or socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The ISO\ C standard includes the functions +\fIfgetpos\fR() +and +\fIfsetpos\fR(), +which work on very large files by use of a special positioning type. +.P +Although +\fIlseek\fR() +may position the file offset beyond the end of the file, this function +does not itself extend the size of the file. While the only function +in POSIX.1\(hy2008 that may directly extend the size of the file is +\fIwrite\fR(), +\fItruncate\fR(), +and +\fIftruncate\fR(), +several functions originally derived from the ISO\ C standard, such as +\fIfwrite\fR(), +\fIfprintf\fR(), +and so on, may do so (by causing calls on +\fIwrite\fR()). +.P +An invalid file offset that would cause +.BR [EINVAL] +to be returned may be both implementation-defined and +device-dependent (for example, memory may have few invalid values). A +negative file offset may be valid for some devices in some +implementations. +.P +The POSIX.1\(hy1990 standard did not specifically prohibit +\fIlseek\fR() +from returning a negative offset. Therefore, an application was +required to clear +.IR errno +prior to the call and check +.IR errno +upon return to determine whether a return value of (\c +.BR off_t )\-1 +is a negative offset or an indication of an error condition. The +standard developers did not wish to require this action on the part of +a conforming application, and chose to require that +.IR errno +be set to +.BR [EINVAL] +when the resulting file offset would be negative for a regular file, +block special file, or directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/lstat.3p b/upstream/archlinux/man3p/lstat.3p new file mode 100644 index 00000000..a1c95bb2 --- /dev/null +++ b/upstream/archlinux/man3p/lstat.3p @@ -0,0 +1,40 @@ +'\" et +.TH LSTAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +lstat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +.P +int lstat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfstatat\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/malloc.3p b/upstream/archlinux/man3p/malloc.3p new file mode 100644 index 00000000..2f65cf34 --- /dev/null +++ b/upstream/archlinux/man3p/malloc.3p @@ -0,0 +1,111 @@ +'\" et +.TH MALLOC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +malloc +\(em a memory allocator +.SH SYNOPSIS +.LP +.nf +#include +.P +void *malloc(size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImalloc\fR() +function shall allocate unused space for an object whose size in +bytes is specified by +.IR size +and whose value is unspecified. +.P +The order and contiguity of storage allocated by successive calls to +\fImalloc\fR() +is unspecified. The pointer returned if the allocation succeeds shall +be suitably aligned so that it may be assigned to a pointer to any type +of object and then used to access such an object in the space allocated +(until the space is explicitly freed or reallocated). Each such +allocation shall yield a pointer to an object disjoint from any other +object. The pointer returned points to the start (lowest byte address) +of the allocated space. If the space cannot be allocated, a null +pointer shall be returned. If the size of the space requested is 0, the +behavior is implementation-defined: either a null pointer shall be +returned, or the behavior shall be as if the size were some non-zero value, +except that the behavior is undefined if the returned pointer is used to +access an object. +.SH "RETURN VALUE" +Upon successful completion with +.IR size +not equal to 0, +\fImalloc\fR() +shall return a pointer to the allocated space. If +.IR size +is 0, either: +.IP " *" 4 +A null pointer shall be returned +and +.IR errno +may be set to an implementation-defined value, +or +.IP " *" 4 +A pointer to the allocated space shall be returned. The application +shall ensure that the pointer is not used to access an object. +.P +Otherwise, it shall return a null pointer +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImalloc\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcalloc\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIposix_memalign\fR\^(\|)", +.IR "\fIrealloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mblen.3p b/upstream/archlinux/man3p/mblen.3p new file mode 100644 index 00000000..9b8e32eb --- /dev/null +++ b/upstream/archlinux/man3p/mblen.3p @@ -0,0 +1,139 @@ +'\" et +.TH MBLEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mblen +\(em get number of bytes in a character +.SH SYNOPSIS +.LP +.nf +#include +.P +int mblen(const char *\fIs\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR s +is not a null pointer, +\fImblen\fR() +shall determine the number of bytes constituting the character +pointed to by +.IR s . +Except that the shift state of +\fImbtowc\fR() +is not affected, it shall be equivalent to: +.sp +.RS 4 +.nf + +mbtowc((wchar_t *)0, \fIs\fP, \fIn\fP); +.fi +.P +.RE +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 +calls +\fImblen\fR(). +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. For a state-dependent encoding, this +function shall be placed into its initial state by a call for which its +character pointer argument, +.IR s , +is a null pointer. Subsequent calls with +.IR s +as other than a null pointer shall cause the internal state of the +function to be altered as necessary. A call with +.IR s +as a null pointer shall cause this function to return a non-zero value +if encodings have state dependency, and 0 otherwise. If the +implementation employs special bytes to change the shift state, these +bytes shall not produce separate wide-character codes, but shall be +grouped with an adjacent character. Changing the +.IR LC_CTYPE +category causes the shift state of this function to be unspecified. +.P +The +\fImblen\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If +.IR s +is a null pointer, +\fImblen\fR() +shall return a non-zero or 0 value, if character encodings, +respectively, do or do not have state-dependent encodings. If +.IR s +is not a null pointer, +\fImblen\fR() +shall either return 0 (if +.IR s +points to the null byte), or return the number of bytes that +constitute the character (if the next +.IR n +or fewer bytes form a valid character), or return \-1 (if they do +not form a valid character) +and may set +.IR errno +to indicate the error. +In no case shall the value returned be greater than +.IR n +or the value of the +{MB_CUR_MAX} +macro. +.SH ERRORS +The +\fImblen\fR() +function may fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. In the POSIX locale an +.BR [EILSEQ] +error cannot occur since all byte values are valid characters. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mbrlen.3p b/upstream/archlinux/man3p/mbrlen.3p new file mode 100644 index 00000000..2d378afa --- /dev/null +++ b/upstream/archlinux/man3p/mbrlen.3p @@ -0,0 +1,164 @@ +'\" et +.TH MBRLEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mbrlen +\(em get number of bytes in a character (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbrlen(const char *restrict \fIs\fP, size_t \fIn\fP, + mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR s +is not a null pointer, +\fImbrlen\fR() +shall determine the number of bytes constituting the character pointed +to by +.IR s . +It shall be equivalent to: +.sp +.RS 4 +.nf + +mbstate_t internal; +mbrtowc(NULL, s, n, ps != NULL ? ps : &internal); +.fi +.P +.RE +.P +If +.IR ps +is a null pointer, the +\fImbrlen\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. The implementation shall behave as +if no function defined in this volume of POSIX.1\(hy2017 calls +\fImbrlen\fR(). +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. +.P +The +\fImbrlen\fR() +function need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fImbrlen\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fImbrlen\fR() +function shall return the first of the following that applies: +.IP 0 12 +If the next +.IR n +or fewer bytes complete the character that corresponds to the null +wide character. +.IP "\fIpositive\fP" 12 +If the next +.IR n +or fewer bytes complete a valid character; the value returned shall +be the number of bytes that complete the character. +.IP "(\fBsize_t\fP)\-2" 12 +If the next +.IR n +bytes contribute to an incomplete but potentially valid character, and +all +.IR n +bytes have been processed. When +.IR n +has at least the value of the +{MB_CUR_MAX} +macro, this case can only occur if +.IR s +points at a sequence of redundant shift sequences (for implementations +with state-dependent encodings). +.IP "(\fBsize_t\fP)\-1" 12 +If an encoding error occurs, in which case the next +.IR n +or fewer bytes do not contribute to a complete and valid character. In +this case, +.BR [EILSEQ] +shall be stored in +.IR errno +and the conversion state is undefined. +.SH ERRORS +The +\fImbrlen\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +In the POSIX locale an +.BR [EILSEQ] +error cannot occur since all byte values are valid characters. +.br +.P +The +\fImbrlen\fR() +function may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mbrtowc.3p b/upstream/archlinux/man3p/mbrtowc.3p new file mode 100644 index 00000000..49e84228 --- /dev/null +++ b/upstream/archlinux/man3p/mbrtowc.3p @@ -0,0 +1,185 @@ +'\" et +.TH MBRTOWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mbrtowc +\(em convert a character to a wide-character code (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbrtowc(wchar_t *restrict \fIpwc\fP, const char *restrict \fIs\fP, + size_t \fIn\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR s +is a null pointer, the +\fImbrtowc\fR() +function shall be equivalent to the call: +.sp +.RS 4 +.nf + +mbrtowc(NULL, "", 1, ps) +.fi +.P +.RE +.P +In this case, the values of the arguments +.IR pwc +and +.IR n +are ignored. +.P +If +.IR s +is not a null pointer, the +\fImbrtowc\fR() +function shall inspect at most +.IR n +bytes beginning at the byte pointed to by +.IR s +to determine the number of bytes needed to complete the next character +(including any shift sequences). If the function determines that the +next character is completed, it shall determine the value of the +corresponding wide character and then, if +.IR pwc +is not a null pointer, shall store that value in the object pointed to by +.IR pwc . +If the corresponding wide character is the null wide character, the +resulting state described shall be the initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fImbrtowc\fR() +function shall use its own internal +.BR mbstate_t +object, which shall be initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. The implementation shall behave as +if no function defined in this volume of POSIX.1\(hy2017 calls +\fImbrtowc\fR(). +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. +.P +The +\fImbrtowc\fR() +function need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fImbrtowc\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fImbrtowc\fR() +function shall return the first of the following that applies: +.IP 0 12 +If the next +.IR n +or fewer bytes complete the character that corresponds to the null wide +character (which is the value stored). +.IP "between 1 and \fIn\fR inclusive" 12 +.br +If the next +.IR n +or fewer bytes complete a valid character (which is the value stored); +the value returned shall be the number of bytes that complete the +character. +.IP "(\fBsize_t\fP)\-2" 12 +If the next +.IR n +bytes contribute to an incomplete but potentially valid character, and +all +.IR n +bytes have been processed (no value is stored). When +.IR n +has at least the value of the +{MB_CUR_MAX} +macro, this case can only occur if +.IR s +points at a sequence of redundant shift sequences (for implementations +with state-dependent encodings). +.IP "(\fBsize_t\fP)\-1" 12 +If an encoding error occurs, in which case the next +.IR n +or fewer bytes do not contribute to a complete and valid character (no +value is stored). In this case, +.BR [EILSEQ] +shall be stored in +.IR errno +and the conversion state is undefined. +.SH ERRORS +The +\fImbrtowc\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +In the POSIX locale an +.BR [EILSEQ] +error cannot occur since all byte values are valid characters. +.P +The +\fImbrtowc\fR() +function may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mbsinit.3p b/upstream/archlinux/man3p/mbsinit.3p new file mode 100644 index 00000000..60a1afcf --- /dev/null +++ b/upstream/archlinux/man3p/mbsinit.3p @@ -0,0 +1,103 @@ +'\" et +.TH MBSINIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mbsinit +\(em determine conversion object status +.SH SYNOPSIS +.LP +.nf +#include +.P +int mbsinit(const mbstate_t *\fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR ps +is not a null pointer, the +\fImbsinit\fR() +function shall determine whether the object pointed to by +.IR ps +describes an initial conversion state. +.SH "RETURN VALUE" +The +\fImbsinit\fR() +function shall return non-zero if +.IR ps +is a null pointer, or if the pointed-to object describes an initial +conversion state; otherwise, it shall return zero. +.P +If an +.BR mbstate_t +object is altered by any of the functions described as ``restartable'', +and is then used with a different character sequence, or in the other +conversion direction, or with a different +.IR LC_CTYPE +category setting than on earlier function calls, the behavior is undefined. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +.BR mbstate_t +object is used to describe the current conversion state from a +particular character sequence to a wide-character sequence (or \fIvice +versa\fP) under the rules of a particular setting of the +.IR LC_CTYPE +category of the current locale. +.P +The initial conversion state corresponds, for a conversion in either +direction, to the beginning of a new character sequence in the initial +shift state. A zero valued +.BR mbstate_t +object is at least one way to describe an initial conversion state. A +zero valued +.BR mbstate_t +object can be used to initiate conversion involving any character +sequence, in any +.IR LC_CTYPE +category setting. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbrlen\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fImbsrtowcs\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)", +.IR "\fIwcsrtombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mbsrtowcs.3p b/upstream/archlinux/man3p/mbsrtowcs.3p new file mode 100644 index 00000000..b384b69b --- /dev/null +++ b/upstream/archlinux/man3p/mbsrtowcs.3p @@ -0,0 +1,188 @@ +'\" et +.TH MBSRTOWCS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mbsnrtowcs, mbsrtowcs +\(em convert a character string to a wide-character string (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbsnrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP, + size_t \fInmc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +size_t mbsrtowcs(wchar_t *restrict \fIdst\fP, const char **restrict \fIsrc\fP, + size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +For +\fImbsrtowcs\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImbsrtowcs\fR() +function shall convert a sequence of characters, beginning in the +conversion state described by the object pointed to by +.IR ps , +from the array indirectly pointed to by +.IR src +into a sequence of corresponding wide characters. If +.IR dst +is not a null pointer, the converted characters shall be stored into +the array pointed to by +.IR dst . +Conversion continues up to and including a terminating null character, +which shall also be stored. Conversion shall stop early in either of +the following cases: +.IP " *" 4 +A sequence of bytes is encountered that does not form a valid character. +.IP " *" 4 +.IR len +codes have been stored into the array pointed to by +.IR dst +(and +.IR dst +is not a null pointer). +.P +Each conversion shall take place as if by a call to the +\fImbrtowc\fR() +function. +.P +If +.IR dst +is not a null pointer, the pointer object pointed to by +.IR src +shall be assigned either a null pointer (if conversion stopped due to +reaching a terminating null character) or the address just past the +last character converted (if any). If conversion stopped due to +reaching a terminating null character, and if +.IR dst +is not a null pointer, the resulting state described shall be the +initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fImbsrtowcs\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. +.P +The +\fImbsnrtowcs\fR() +function shall be equivalent to the +\fImbsrtowcs\fR() +function, except that the conversion of characters indirectly +pointed to by +.IR src +is limited to at most +.IR nmc +bytes (the size of the input buffer), and under conditions where +\fImbsrtowcs\fR() +would assign the address just past the last character converted (if any) +to the pointer object pointed to by +.IR src , +\fImbsnrtowcs\fR() +shall instead assign the address just past the last byte processed +(if any) to that pointer object. If the input buffer ends with an +incomplete character, it is unspecified whether conversion stops at +the end of the previous character (if any), or at the end of the input +buffer. In the latter case, a subsequent call to +\fImbsnrtowcs\fR() +with an input buffer that starts with the remainder of the incomplete +character shall correctly complete the conversion of that character. +.P +The behavior of these functions shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 +calls these functions. +.P +The +\fImbsnrtowcs\fR() +and +\fImbsrtowcs\fR() +functions need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fImbsrtowcs\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +If the input conversion encounters a sequence of bytes that do not form +a valid character, an encoding error occurs. In this case, these +functions shall store the value of the macro +.BR [EILSEQ] +in +.IR errno +and shall return (\fBsize_t\fP)\-1; the conversion state is undefined. +Otherwise, these functions shall return the number of characters +successfully converted, not including the terminating null (if any). +.SH ERRORS +These functions shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. +In the POSIX locale an +.BR [EILSEQ] +error cannot occur since all byte values are valid characters. +.P +These functions may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version may require that when the input buffer ends with +an incomplete character, conversion stops at the end of the input buffer. +.SH "SEE ALSO" +.IR "\fIiconv\fR\^(\|)", +.IR "\fImbrtowc\fR\^(\|)", +.IR "\fImbsinit\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mbstowcs.3p b/upstream/archlinux/man3p/mbstowcs.3p new file mode 100644 index 00000000..ca98d55b --- /dev/null +++ b/upstream/archlinux/man3p/mbstowcs.3p @@ -0,0 +1,123 @@ +'\" et +.TH MBSTOWCS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mbstowcs +\(em convert a character string to a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t mbstowcs(wchar_t *restrict \fIpwcs\fP, const char *restrict \fIs\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImbstowcs\fR() +function shall convert a sequence of characters that begins in the +initial shift state from the array pointed to by +.IR s +into a sequence of corresponding wide-character codes and shall store +not more than +.IR n +wide-character codes into the array pointed to by +.IR pwcs . +No characters that follow a null byte (which is converted into a +wide-character code with value 0) shall be examined or converted. Each +character shall be converted as if by a call to +\fImbtowc\fR(), +except that the shift state of +\fImbtowc\fR() +is not affected. +.P +No more than +.IR n +elements shall be modified in the array pointed to by +.IR pwcs . +If copying takes place between objects that overlap, the behavior is +undefined. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +If +.IR pwcs +is a null pointer, +\fImbstowcs\fR() +shall return the length required to convert the entire array regardless +of the value of +.IR n , +but no values are stored. +.SH "RETURN VALUE" +If an invalid character is encountered, +\fImbstowcs\fR() +shall return (\fBsize_t\fP)\-1 +and shall set +.IR errno +to indicate the error. +.P +Otherwise, +\fImbstowcs\fR() +shall return the number of the array elements modified +(or required if +.IR pwcs +is null), +not including a terminating 0 code, if any. The array shall +not be zero-terminated if the value returned is +.IR n . +.SH ERRORS +The +\fImbstowcs\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. In the POSIX locale an +.BR [EILSEQ] +error cannot occur since all byte values are valid characters. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mbtowc.3p b/upstream/archlinux/man3p/mbtowc.3p new file mode 100644 index 00000000..2e62792e --- /dev/null +++ b/upstream/archlinux/man3p/mbtowc.3p @@ -0,0 +1,143 @@ +'\" et +.TH MBTOWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mbtowc +\(em convert a character to a wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int mbtowc(wchar_t *restrict \fIpwc\fP, const char *restrict \fIs\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR s +is not a null pointer, +\fImbtowc\fR() +shall determine the number of bytes that constitute the character +pointed to by +.IR s . +It shall then determine the wide-character code for the value of type +.BR wchar_t +that corresponds to that character. (The value of the wide-character +code corresponding to the null byte is 0.) If the character is valid +and +.IR pwc +is not a null pointer, +\fImbtowc\fR() +shall store the wide-character code in the object pointed to by +.IR pwc . +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. For a state-dependent encoding, this +function is placed into its initial state by a call for which its +character pointer argument, +.IR s , +is a null pointer. Subsequent calls with +.IR s +as other than a null pointer shall cause the internal state of the +function to be altered as necessary. A call with +.IR s +as a null pointer shall cause this function to return a non-zero value +if encodings have state dependency, and 0 otherwise. If the +implementation employs special bytes to change the shift state, these +bytes shall not produce separate wide-character codes, but shall be +grouped with an adjacent character. Changing the +.IR LC_CTYPE +category causes the shift state of this function to be unspecified. At +most +.IR n +bytes of the array pointed to by +.IR s +shall be examined. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 calls +\fImbtowc\fR(). +.P +The +\fImbtowc\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If +.IR s +is a null pointer, +\fImbtowc\fR() +shall return a non-zero or 0 value, if character encodings, respectively, +do or do not have state-dependent encodings. If +.IR s +is not a null pointer, +\fImbtowc\fR() +shall either return 0 (if +.IR s +points to the null byte), or return the number of bytes that constitute +the converted character (if the next +.IR n +or fewer bytes form a valid character), or return \-1 +and shall set +.IR errno +to indicate the error +(if they do not form a valid character). +.P +In no case shall the value returned be greater than +.IR n +or the value of the +{MB_CUR_MAX} +macro. +.SH ERRORS +The +\fImbtowc\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected. In the POSIX locale an +.BR [EILSEQ] +error cannot occur since all byte values are valid characters. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/memccpy.3p b/upstream/archlinux/man3p/memccpy.3p new file mode 100644 index 00000000..99154f75 --- /dev/null +++ b/upstream/archlinux/man3p/memccpy.3p @@ -0,0 +1,83 @@ +'\" et +.TH MEMCCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +memccpy +\(em copy bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memccpy(void *restrict \fIs1\fP, const void *restrict \fIs2\fP, + int \fIc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The +\fImemccpy\fR() +function shall copy bytes from memory area +.IR s2 +into +.IR s1 , +stopping after the first occurrence of byte +.IR c +(converted to an +.BR "unsigned char" ) +is copied, or after +.IR n +bytes are copied, whichever comes first. If copying takes place +between objects that overlap, the behavior is undefined. +.SH "RETURN VALUE" +The +\fImemccpy\fR() +function shall return a pointer to the byte after the copy of +.IR c +in +.IR s1 , +or a null pointer if +.IR c +was not found in the first +.IR n +bytes of +.IR s2 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImemccpy\fR() +function does not check for the overflow of the receiving memory area. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/memchr.3p b/upstream/archlinux/man3p/memchr.3p new file mode 100644 index 00000000..3ac023e0 --- /dev/null +++ b/upstream/archlinux/man3p/memchr.3p @@ -0,0 +1,83 @@ +'\" et +.TH MEMCHR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +memchr +\(em find byte in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memchr(const void *\fIs\fP, int \fIc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImemchr\fR() +function shall locate the first occurrence of +.IR c +(converted to an +.BR "unsigned char" ) +in the initial +.IR n +bytes (each interpreted as +.BR "unsigned char" ) +pointed to by +.IR s . +.P +Implementations shall behave as if they read the memory byte by byte +from the beginning of the bytes pointed to by +.IR s +and stop at the first occurrence of +.IR c +(if it is found in the initial +.IR n +bytes). +.SH "RETURN VALUE" +The +\fImemchr\fR() +function shall return a pointer to the located byte, or a null pointer +if the byte is not found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/memcmp.3p b/upstream/archlinux/man3p/memcmp.3p new file mode 100644 index 00000000..0697d3f2 --- /dev/null +++ b/upstream/archlinux/man3p/memcmp.3p @@ -0,0 +1,84 @@ +'\" et +.TH MEMCMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +memcmp +\(em compare bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +int memcmp(const void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImemcmp\fR() +function shall compare the first +.IR n +bytes (each interpreted as +.BR "unsigned char" ) +of the object pointed to by +.IR s1 +to the first +.IR n +bytes of the object pointed to by +.IR s2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of bytes (both +interpreted as type +.BR "unsigned char" ) +that differ in the objects being compared. +.SH "RETURN VALUE" +The +\fImemcmp\fR() +function shall return an integer greater than, equal to, or less than +0, if the object pointed to by +.IR s1 +is greater than, equal to, or less than the object pointed to by +.IR s2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/memcpy.3p b/upstream/archlinux/man3p/memcpy.3p new file mode 100644 index 00000000..4ad69c51 --- /dev/null +++ b/upstream/archlinux/man3p/memcpy.3p @@ -0,0 +1,76 @@ +'\" et +.TH MEMCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +memcpy +\(em copy bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memcpy(void *restrict \fIs1\fP, const void *restrict \fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImemcpy\fR() +function shall copy +.IR n +bytes from the object pointed to by +.IR s2 +into the object pointed to by +.IR s1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fImemcpy\fR() +function shall return +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImemcpy\fR() +function does not check for the overflow of the receiving memory +area. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/memmove.3p b/upstream/archlinux/man3p/memmove.3p new file mode 100644 index 00000000..93c973e9 --- /dev/null +++ b/upstream/archlinux/man3p/memmove.3p @@ -0,0 +1,85 @@ +'\" et +.TH MEMMOVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +memmove +\(em copy bytes in memory with overlapping areas +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memmove(void *\fIs1\fP, const void *\fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImemmove\fR() +function shall copy +.IR n +bytes from the object pointed to by +.IR s2 +into the object pointed to by +.IR s1 . +Copying takes place as if the +.IR n +bytes from the object pointed to by +.IR s2 +are first copied into a temporary array of +.IR n +bytes that does not overlap the objects pointed to by +.IR s1 +and +.IR s2 , +and then the +.IR n +bytes from the temporary array are copied into the object pointed to by +.IR s1 . +.SH "RETURN VALUE" +The +\fImemmove\fR() +function shall return +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/memset.3p b/upstream/archlinux/man3p/memset.3p new file mode 100644 index 00000000..71aa3d0e --- /dev/null +++ b/upstream/archlinux/man3p/memset.3p @@ -0,0 +1,73 @@ +'\" et +.TH MEMSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +memset +\(em set bytes in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *memset(void *\fIs\fP, int \fIc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImemset\fR() +function shall copy +.IR c +(converted to an +.BR "unsigned char" ) +into each of the first +.IR n +bytes of the object pointed to by +.IR s . +.SH "RETURN VALUE" +The +\fImemset\fR() +function shall return +.IR s ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mkdir.3p b/upstream/archlinux/man3p/mkdir.3p new file mode 100644 index 00000000..266cc21b --- /dev/null +++ b/upstream/archlinux/man3p/mkdir.3p @@ -0,0 +1,264 @@ +'\" et +.TH MKDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mkdir, mkdirat +\(em make a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkdir(const char *\fIpath\fP, mode_t \fImode\fP); +.P +#include +.P +int mkdirat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fImkdir\fR() +function shall create a new directory with name +.IR path . +The file permission bits of the new directory shall be initialized from +.IR mode . +These file permission bits of the +.IR mode +argument shall be modified by the process' file creation mask. +.P +When bits in +.IR mode +other than the file permission bits are set, the meaning of these +additional bits is implementation-defined. +.P +The directory's user ID shall be set to the process' effective user ID. +The directory's group ID shall be set to the group ID of the parent +directory or to the effective group ID of the process. Implementations +shall provide a way to initialize the directory's group ID to the group +ID of the parent directory. Implementations may, but need not, provide +an implementation-defined way to initialize the directory's group ID to +the effective group ID of the calling process. +.P +The newly created directory shall be an empty directory. +.P +If +.IR path +names a symbolic link, +\fImkdir\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +Upon successful completion, +\fImkdir\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the directory. Also, the last +data modification and last file status change timestamps of the directory +that contains the new entry shall be marked for update. +.P +The +\fImkdirat\fR() +function shall be equivalent to the +\fImkdir\fR() +function except in the case where +.IR path +specifies a relative path. In this case the newly created directory is +created relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +If +\fImkdirat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fImkdir\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, no directory shall be created. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or write +permission is denied on the parent directory of the directory to be +created. +.TP +.BR EEXIST +The named file exists. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMLINK +The link count of the parent directory would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix specified by +.IR path +does not name an existing directory or +.IR path +is an empty string. +.TP +.BR ENOSPC +The file system does not contain enough space to hold the contents of +the new directory or to extend the parent directory of the new +directory. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The parent directory resides on a read-only file system. +.P +In addition, the +\fImkdirat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Directory" +.P +The following example shows how to create a directory named +.BR /home/cnd/mod1 , +with read/write/search permissions for owner and group, and with +read/search permissions for others. +.sp +.RS 4 +.nf + +#include +#include +.P +int status; +\&... +status = mkdir("/home/cnd/mod1", S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fImkdir\fR() +function originated in 4.2 BSD and was added to System V in Release 3.0. +.P +4.3 BSD detects +.BR [ENAMETOOLONG] . +.P +The POSIX.1\(hy1990 standard required that the group ID of a newly created directory be +set to the group ID of its parent directory or to the effective group +ID of the creating process. FIPS 151\(hy2 required that implementations provide +a way to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the directory is created, or determine under +what conditions the implementation will set the desired group ID. +.P +The purpose of the +\fImkdirat\fR() +function is to create a directory in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to the call to +\fImkdir\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fImkdirat\fR() +function it can be guaranteed that the newly created directory is +located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mkdtemp.3p b/upstream/archlinux/man3p/mkdtemp.3p new file mode 100644 index 00000000..ddeff2e1 --- /dev/null +++ b/upstream/archlinux/man3p/mkdtemp.3p @@ -0,0 +1,249 @@ +'\" et +.TH MKDTEMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mkdtemp, mkstemp +\(em create a unique directory or file +.SH SYNOPSIS +.LP +.nf +#include +.P +char *mkdtemp(char *\fItemplate\fP); +int mkstemp(char *\fItemplate\fP); +.fi +.SH DESCRIPTION +The +\fImkdtemp\fR() +function shall create a directory with a unique name derived from +.IR template . +The application shall ensure that the string provided in +.IR template +is a pathname ending with at least six trailing +.BR 'X' +characters. The +\fImkdtemp\fR() +function shall modify the contents of +.IR template +by replacing six or more +.BR 'X' +characters at the end of the pathname with the same number of +characters from the portable filename character set. The characters +shall be chosen such that the resulting pathname does not duplicate +the name of an existing file at the time of the call to +\fImkdtemp\fR(). +The +\fImkdtemp\fR() +function shall use the resulting pathname to create the new directory +as if by a call to: +.sp +.RS 4 +.nf + +mkdir(pathname, S_IRWXU) +.fi +.P +.RE +.P +The +\fImkstemp\fR() +function shall create a regular file with a unique name derived from +.IR template +and return a file descriptor for the file open for reading and +writing. The application shall ensure that the string provided in +.IR template +is a pathname ending with at least six trailing +.BR 'X' +characters. The +\fImkstemp\fR() +function shall modify the contents of +.IR template +by replacing six or more +.BR 'X' +characters at the end of the pathname with the same number of +characters from the portable filename character set. The characters +shall be chosen such that the resulting pathname does not duplicate +the name of an existing file at the time of the call to +\fImkstemp\fR(). +The +\fImkstemp\fR() +function shall use the resulting pathname to create the file, and +obtain a file descriptor for it, as if by a call to: +.sp +.RS 4 +.nf + +open(pathname, O_RDWR|O_CREAT|O_EXCL, S_IRUSR|S_IWUSR) +.fi +.P +.RE +.P +By behaving as if the O_EXCL flag for +\fIopen\fR() +is set, the function prevents any possible race condition between +testing whether the file exists and opening it for use. +.SH "RETURN VALUE" +Upon successful completion, the +\fImkdtemp\fR() +function shall return the value of +.IR template . +Otherwise, it shall return a null pointer and shall set +.IR errno +to indicate the error. +.P +Upon successful completion, the +\fImkstemp\fR() +function shall return an open file descriptor. Otherwise, it shall +return \-1 and shall set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImkdtemp\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or write +permission is denied on the parent directory of the directory to be +created. +.TP +.BR EINVAL +The string pointed to by +.IR template +does not end in +.BR \(dqXXXXXX\(dq . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +path of the directory to be created. +.TP +.BR EMLINK +The link count of the parent directory would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix specified by the +.IR template +argument does not name an existing directory. +.TP +.BR ENOSPC +The file system does not contain enough space to hold the contents of +the new directory or to extend the parent directory of the new +directory. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The parent directory resides on a read-only file system. +.P +The +\fImkdtemp\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the path of the +directory to be created. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.P +The error conditions for the +\fImkstemp\fR() +function are defined in +.IR "\fIopen\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pathname" +.P +The following example creates a file with a 10-character name beginning +with the characters +.BR \(dqfile\(dq +and opens the file for reading and writing. The value returned as the +value of +.IR fd +is a file descriptor that identifies the file. +.sp +.RS 4 +.nf + +#include +\&... +char template[] = "/tmp/fileXXXXXX"; +int fd; +.P +fd = mkstemp(template); +.fi +.P +.RE +.SH "APPLICATION USAGE" +It is possible to run out of letters. +.P +Portable applications should pass exactly six trailing +.BR 'X' s +in the template and no more; implementations may treat any additional +trailing +.BR 'X' s +as either a fixed or replaceable part of the template. To be sure of +only passing six, a fixed string of at least one non-\c +.BR 'X' +character should precede the six +.BR 'X' s. +.P +Since +.BR 'X' +is in the portable filename character set, some of the replacement +characters can be +.BR 'X' s, +leaving part (or even all) of the template effectively unchanged. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetpid\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mkfifo.3p b/upstream/archlinux/man3p/mkfifo.3p new file mode 100644 index 00000000..e25398f6 --- /dev/null +++ b/upstream/archlinux/man3p/mkfifo.3p @@ -0,0 +1,282 @@ +'\" et +.TH MKFIFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mkfifo, mkfifoat +\(em make a FIFO special file +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkfifo(const char *\fIpath\fP, mode_t \fImode\fP); +.P +#include +.P +int mkfifoat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fImkfifo\fR() +function shall create a new FIFO special file named by the pathname +pointed to by +.IR path . +The file permission bits of the new FIFO shall be initialized from +.IR mode . +The file permission bits of the +.IR mode +argument shall be modified by the process' file creation mask. +.P +When bits in +.IR mode +other than the file permission bits are set, the effect is +implementation-defined. +.P +If +.IR path +names a symbolic link, +\fImkfifo\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +The FIFO's user ID shall be set to the process' effective user ID. The +FIFO's group ID shall be set to the group ID of the parent directory or +to the effective group ID of the process. Implementations shall provide +a way to initialize the FIFO's group ID to the group ID of the parent +directory. Implementations may, but need not, provide an +implementation-defined way to initialize the FIFO's group ID to the +effective group ID of the calling process. +.P +Upon successful completion, +\fImkfifo\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the file. Also, the last +data modification and last file status change timestamps of the directory +that contains the new entry shall be marked for update. +.P +The +\fImkfifoat\fR() +function shall be equivalent to the +\fImkfifo\fR() +function except in the case where +.IR path +specifies a relative path. In this case the newly created FIFO is +created relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +If +\fImkfifoat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fImkfifo\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, no FIFO shall be created. +.SH ERRORS +These functions shall fail if: +.TP +.BR 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. +.TP +.BR EEXIST +The named file already exists. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path +without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory that would contain the new file cannot be extended or the +file system is out of file-allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The named file resides on a read-only file system. +.P +The +\fImkfifoat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a FIFO File" +.P +The following example shows how to create a FIFO file named +.BR /home/cnd/mod_done , +with read/write permissions for owner, and with read permissions for +group and others. +.sp +.RS 4 +.nf + +#include +#include +.P +int status; +\&... +status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | + S_IRGRP | S_IROTH); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The syntax of this function is intended to maintain compatibility with +historical implementations of +\fImknod\fR(). +The latter function was included in the 1984 /usr/group standard but only for use in +creating FIFO special files. The +\fImknod\fR() +function was originally excluded from the POSIX.1\(hy1988 standard as +implementation-defined and replaced by +\fImkdir\fR() +and +\fImkfifo\fR(). +The +\fImknod\fR() +function is now included for alignment with the Single UNIX Specification. +.P +The POSIX.1\(hy1990 standard required that the group ID of a newly created FIFO be +set to the group ID of its parent directory or to the effective group +ID of the creating process. FIPS 151\(hy2 required that implementations provide +a way to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the FIFO is created, or determine under +what conditions the implementation will set the desired group ID. +.P +The purpose of the +\fImkfifoat\fR() +function is to create a FIFO special file in directories other than +the current working directory without exposure to race conditions. Any +part of the path of a file could be changed in parallel to a call to +\fImkfifo\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fImkfifoat\fR() +function it can be guaranteed that the newly created FIFO is located +relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mknod.3p b/upstream/archlinux/man3p/mknod.3p new file mode 100644 index 00000000..3f4d4454 --- /dev/null +++ b/upstream/archlinux/man3p/mknod.3p @@ -0,0 +1,345 @@ +'\" et +.TH MKNOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mknod, mknodat +\(em make directory, special file, or regular file +.SH SYNOPSIS +.LP +.nf +#include +.P +int mknod(const char *\fIpath\fP, mode_t \fImode\fP, dev_t \fIdev\fP); +.P +#include +.P +int mknodat(int \fIfd\fP, const char *\fIpath\fP, mode_t \fImode\fP, dev_t \fIdev\fP); +.fi +.SH DESCRIPTION +The +\fImknod\fR() +function shall create a new file named by the pathname to which the +argument +.IR path +points. +.P +The file type for +.IR path +is OR'ed into the +.IR mode +argument, and the application shall select one of the following +symbolic constants: +.TS +tab(!) box center; +cB | cB +lw(1i) | lw(3i). +Name!Description +_ +S_IFIFO!FIFO-special +S_IFCHR!Character-special (non-portable) +S_IFDIR!Directory (non-portable) +S_IFBLK!Block-special (non-portable) +S_IFREG!Regular (non-portable) +.TE +.P +The only portable use of +\fImknod\fR() +is to create a FIFO-special file. If +.IR mode +is not S_IFIFO or +.IR dev +is not 0, the behavior of +\fImknod\fR() +is unspecified. +.P +The permissions for the new file are OR'ed into the +.IR mode +argument, and may be selected from any combination of the following +symbolic constants: +.TS +tab(!) box center; +cB | cB +lw(1i) | lw(3i). +Name!Description +_ +S_ISUID!Set user ID on execution. +S_ISGID!Set group ID on execution. +S_IRWXU!Read, write, or execute (search) by owner. +S_IRUSR!Read by owner. +S_IWUSR!Write by owner. +S_IXUSR!Execute (search) by owner. +S_IRWXG!Read, write, or execute (search) by group. +S_IRGRP!Read by group. +S_IWGRP!Write by group. +S_IXGRP!Execute (search) by group. +S_IRWXO!Read, write, or execute (search) by others. +S_IROTH!Read by others. +S_IWOTH!Write by others. +S_IXOTH!Execute (search) by others. +S_ISVTX!On directories, restricted deletion flag. +.TE +.P +The user ID of the file shall be initialized to the effective user ID +of the process. The group ID of the file shall be initialized to either +the effective group ID of the process or the group ID of the parent +directory. Implementations shall provide a way to initialize the file's +group ID to the group ID of the parent directory. Implementations may, +but need not, provide an implementation-defined way to initialize the +file's group ID to the effective group ID of the calling process. The +owner, group, and other permission bits of +.IR mode +shall be modified by the file mode creation mask of the process. The +\fImknod\fR() +function shall clear each bit whose corresponding bit in the file mode +creation mask of the process is set. +.P +If +.IR path +names a symbolic link, +\fImknod\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +Upon successful completion, +\fImknod\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the file. Also, the last +data modification and last file status change timestamps of the directory +that contains the new entry shall be marked for update. +.P +Only a process with appropriate privileges may invoke +\fImknod\fR() +for file types other than FIFO-special. +.P +The +\fImknodat\fR() +function shall be equivalent to the +\fImknod\fR() +function except in the case where +.IR path +specifies a relative path. In this case the newly created +directory, special file, or regular file is located relative to the +directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +If +\fImknodat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fImknod\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, the new file shall +not be created. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +A component of the path prefix denies search permission, or write +permission is denied on the parent directory. +.TP +.BR EEXIST +The named file exists. +.TP +.BR EINVAL +An invalid argument exists. +.TP +.BR EIO +An I/O error occurred while accessing the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path +without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory that would contain the new file cannot be extended or the +file system is out of file allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The invoking process does not have appropriate privileges and the +file type is not FIFO-special. +.TP +.BR EROFS +The directory in which the file is to be created is located on a +read-only file system. +.br +.P +The +\fImknodat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a FIFO Special File" +.P +The following example shows how to create a FIFO special file named +.BR /home/cnd/mod_done , +with read/write permissions for owner, and with read permissions for +group and others. +.sp +.RS 4 +.nf + +#include +#include +.P +dev_t dev; +int status; +\&... +status = mknod("/home/cnd/mod_done", S_IFIFO | S_IWUSR | + S_IRUSR | S_IRGRP | S_IROTH, dev); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fImkfifo\fR() +function is preferred over this function for making FIFO special files. +.SH RATIONALE +The POSIX.1\(hy1990 standard required that the group ID of a newly created file be +set to the group ID of its parent directory or to the effective group +ID of the creating process. FIPS 151\(hy2 required that implementations provide +a way to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the file is created, or determine under +what conditions the implementation will set the desired group ID. +.P +The purpose of the +\fImknodat\fR() +function is to create directories, special files, or regular files in +directories other than the current working directory without exposure +to race conditions. Any part of the path of a file could be changed in +parallel to a call to +\fImknod\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fImknodat\fR() +function it can be guaranteed that the newly created directory, special +file, or regular file is located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mkstemp.3p b/upstream/archlinux/man3p/mkstemp.3p new file mode 100644 index 00000000..6ad83d8e --- /dev/null +++ b/upstream/archlinux/man3p/mkstemp.3p @@ -0,0 +1,40 @@ +'\" et +.TH MKSTEMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mkstemp +\(em create a unique file +.SH SYNOPSIS +.LP +.nf +#include +.P +int mkstemp(char *\fItemplate\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImkdtemp\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mktime.3p b/upstream/archlinux/man3p/mktime.3p new file mode 100644 index 00000000..a290ac27 --- /dev/null +++ b/upstream/archlinux/man3p/mktime.3p @@ -0,0 +1,187 @@ +'\" et +.TH MKTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mktime +\(em convert broken-down time into time since the Epoch +.SH SYNOPSIS +.LP +.nf +#include +.P +time_t mktime(struct tm *\fItimeptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fImktime\fR() +function shall convert the broken-down time, expressed as local time, +in the structure pointed to by +.IR timeptr , +into a time since the Epoch value with the same encoding as that of the +values returned by +\fItime\fR(). +The original values of the +.IR tm_wday +and +.IR tm_yday +components of the structure shall be ignored, and the original values +of the other components shall not be restricted to the ranges +described in +.IR . +.P +A positive or 0 value for +.IR tm_isdst +shall cause +\fImktime\fR() +to presume initially that Daylight Savings Time, respectively, is or is +not in effect for the specified time. A negative value for +.IR tm_isdst +shall cause +\fImktime\fR() +to attempt to determine whether Daylight Savings Time is in effect for +the specified time. +.P +Local timezone information shall be set as though +\fImktime\fR() +called +\fItzset\fR(). +.P +The relationship between the +.BR tm +structure (defined in the +.IR +header) and the time in seconds since the Epoch is that the result +shall be as specified in the expression given in the definition of +seconds since the Epoch (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.16" ", " "Seconds Since the Epoch") +corrected for timezone and any seasonal time adjustments, where the +names other than +.IR tm_yday +in the structure and in the expression correspond, and the +.IR tm_yday +value used in the expression is the day of the year from 0 to 365 +inclusive, calculated from the other +.BR tm +structure members specified in +.IR +(excluding +.IR tm_wday ). +.P +Upon successful completion, the values of the +.IR tm_wday +and +.IR tm_yday +components of the structure shall be set appropriately, and the other +components shall be set to represent the specified time since the Epoch, +but with their values forced to the ranges indicated in the +.IR +entry; the final value of +.IR tm_mday +shall not be set until +.IR tm_mon +and +.IR tm_year +are determined. +.SH "RETURN VALUE" +The +\fImktime\fR() +function shall return the specified time since the Epoch encoded as +a value of type +.BR time_t . +If the time since the Epoch cannot be represented, the function shall +return the value (\fBtime_t\fP)\-1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImktime\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The result cannot be represented. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +What day of the week is July 4, 2001? +.sp +.RS 4 +.nf + +#include +#include +.P +struct tm time_str; +.P +char daybuf[20]; +.P +int main(void) +{ + time_str.tm_year = 2001 \(em 1900; + time_str.tm_mon = 7 \(em 1; + time_str.tm_mday = 4; + time_str.tm_hour = 0; + time_str.tm_min = 0; + time_str.tm_sec = 1; + time_str.tm_isdst = -1; + if (mktime(&time_str) == -1) + (void)puts("-unknown-"); + else { + (void)strftime(daybuf, sizeof(daybuf), "%A", &time_str); + (void)puts(daybuf); + } + return 0; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.16" ", " "Seconds Since the Epoch", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mlock.3p b/upstream/archlinux/man3p/mlock.3p new file mode 100644 index 00000000..d38c2cb0 --- /dev/null +++ b/upstream/archlinux/man3p/mlock.3p @@ -0,0 +1,170 @@ +'\" et +.TH MLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mlock, +munlock +\(em lock or unlock a range of process address space +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mlock(const void *\fIaddr\fP, size_t \fIlen\fP); +int munlock(const void *\fIaddr\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fImlock\fR() +function shall cause those whole pages containing any part of the +address space of the process starting at address +.IR addr +and continuing for +.IR len +bytes to be memory-resident until unlocked or until the process exits +or +.IR exec s +another process image. The implementation may require that +.IR addr +be a multiple of +{PAGESIZE}. +.P +The +\fImunlock\fR() +function shall unlock those whole pages containing any part of the +address space of the process starting at address +.IR addr +and continuing for +.IR len +bytes, regardless of how many times +\fImlock\fR() +has been called by the process for any of the pages in the specified +range. The implementation may require that +.IR addr +be a multiple of +{PAGESIZE}. +.P +If any of the pages in the range specified to a call to +\fImunlock\fR() +are also mapped into the address spaces of other processes, any locks +established on those pages by another process are unaffected by the +call of this process to +\fImunlock\fR(). +If any of the pages in the range specified by a call to +\fImunlock\fR() +are also mapped into other portions of the address space of the calling +process outside the range specified, any locks established on those +pages via the other mappings are also unaffected by this call. +.P +Upon successful return from +\fImlock\fR(), +pages in the specified range shall be locked and memory-resident. Upon +successful return from +\fImunlock\fR(), +pages in the specified range shall be unlocked with respect to the +address space of the process. Memory residency of unlocked pages is +unspecified. +.P +Appropriate privileges are required to lock process memory with +\fImlock\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fImlock\fR() +and +\fImunlock\fR() +functions shall return a value of zero. Otherwise, no change is made to +any locks in the address space of the process, and the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImlock\fR() +and +\fImunlock\fR() +functions shall fail if: +.TP +.BR ENOMEM +Some or all of the address range specified by the +.IR addr +and +.IR len +arguments does not correspond to valid mapped pages in the address +space of the process. +.P +The +\fImlock\fR() +function shall fail if: +.TP +.BR EAGAIN +Some or all of the memory identified by the operation could not be +locked when the call was made. +.P +The +\fImlock\fR() +and +\fImunlock\fR() +functions may fail if: +.TP +.BR EINVAL +The +.IR addr +argument is not a multiple of +{PAGESIZE}. +.P +The +\fImlock\fR() +function may fail if: +.TP +.BR ENOMEM +Locking the pages mapped by the specified range would exceed an +implementation-defined limit on the amount of memory that the process +may lock. +.TP +.BR EPERM +The calling process does not have appropriate privileges to perform +the requested operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mlockall.3p b/upstream/archlinux/man3p/mlockall.3p new file mode 100644 index 00000000..53fa1908 --- /dev/null +++ b/upstream/archlinux/man3p/mlockall.3p @@ -0,0 +1,160 @@ +'\" et +.TH MLOCKALL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mlockall, +munlockall +\(em lock/unlock the address space of a process +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mlockall(int \fIflags\fP); +int munlockall(void); +.fi +.SH DESCRIPTION +The +\fImlockall\fR() +function shall cause all of the pages mapped by the address space of a +process to be memory-resident until unlocked or until the process exits +or +.IR exec s +another process image. The +.IR flags +argument determines whether the pages to be locked are those currently +mapped by the address space of the process, those that are mapped +in the future, or both. The +.IR flags +argument is constructed from the bitwise-inclusive OR of one or more +of the following symbolic constants, defined in +.IR : +.IP MCL_CURRENT 12 +Lock all of the pages currently mapped into the address space of the +process. +.IP MCL_FUTURE 12 +Lock all of the pages that become mapped into the address space of the +process in the future, when those mappings are established. +.P +If MCL_FUTURE is specified, and the automatic locking of future +mappings eventually causes the amount of locked memory to exceed the +amount of available physical memory or any other +implementation-defined limit, the behavior is +implementation-defined. The manner in which the implementation +informs the application of these situations is also +implementation-defined. +.P +The +\fImunlockall\fR() +function shall unlock all currently mapped pages of the address space +of the process. Any pages that become mapped into the address space of +the process after a call to +\fImunlockall\fR() +shall not be locked, unless there is an intervening call to +\fImlockall\fR() +specifying MCL_FUTURE or a subsequent call to +\fImlockall\fR() +specifying MCL_CURRENT. If pages mapped into the address space of the +process are also mapped into the address spaces of other processes and +are locked by those processes, the locks established by the other +processes shall be unaffected by a call by this process to +\fImunlockall\fR(). +.P +Upon successful return from the +\fImlockall\fR() +function that specifies MCL_CURRENT, all currently mapped pages of the +address space of the process shall be memory-resident and locked. +Upon return from the +\fImunlockall\fR() +function, all currently mapped pages of the address space of the process +shall be unlocked with respect to the address space of the process. +The memory residency of unlocked pages is unspecified. +.P +Appropriate privileges are required to lock process memory with +\fImlockall\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fImlockall\fR() +function shall return a value of zero. Otherwise, no additional memory +shall be locked, and the function shall return a value of \-1 and set +.IR errno +to indicate the error. The effect of failure of +\fImlockall\fR() +on previously existing locks in the address space is unspecified. +.P +If it is supported by the implementation, the +\fImunlockall\fR() +function shall always return a value of zero. Otherwise, the function +shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImlockall\fR() +function shall fail if: +.TP +.BR EAGAIN +Some or all of the memory identified by the operation could not be +locked when the call was made. +.TP +.BR EINVAL +The +.IR flags +argument is zero, or includes unimplemented flags. +.P +The +\fImlockall\fR() +function may fail if: +.TP +.BR ENOMEM +Locking all of the pages currently mapped into the address space of the +process would exceed an implementation-defined limit on the amount of +memory that the process may lock. +.TP +.BR EPERM +The calling process does not have appropriate privileges to perform +the requested operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fImlock\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mmap.3p b/upstream/archlinux/man3p/mmap.3p new file mode 100644 index 00000000..4ba4a50e --- /dev/null +++ b/upstream/archlinux/man3p/mmap.3p @@ -0,0 +1,736 @@ +'\" et +.TH MMAP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mmap +\(em map pages of memory +.SH SYNOPSIS +.LP +.nf +#include +.P +void *mmap(void *\fIaddr\fP, size_t \fIlen\fP, int \fIprot\fP, int \fIflags\fP, + int \fIfildes\fP, off_t \fIoff\fP); +.fi +.SH DESCRIPTION +The +\fImmap\fR() +function shall establish a mapping between an address space +of a process and a memory object. +.P +The +\fImmap\fR() +function shall be supported for the following memory objects: +.IP " *" 4 +Regular files +.IP " *" 4 +Shared memory objects +.IP " *" 4 +Typed memory objects +.P +Support for any other type of file is unspecified. +.P +The format of the call is as follows: +.sp +.RS 4 +.nf + +\fIpa\fR=\fImmap\fR(\fIaddr\fP, \fIlen\fP, \fIprot\fP, \fIflags\fP, \fIfildes\fP, \fIoff\fP); +.fi +.P +.RE +.P +The +\fImmap\fR() +function shall establish a mapping between the address space of the +process at an address +.IR pa +for +.IR len +bytes to the memory object represented by the file descriptor +.IR fildes +at offset +.IR off +for +.IR len +bytes. The value of +.IR pa +is an implementation-defined function of the parameter +.IR addr +and the values of +.IR flags , +further described below. A successful +\fImmap\fR() +call shall return +.IR pa +as its result. The address range starting at +.IR pa +and continuing for +.IR len +bytes shall be legitimate for the possible (not necessarily current) +address space of the process. The range of bytes starting at +.IR off +and continuing for +.IR len +bytes shall be legitimate for the possible (not necessarily current) +offsets in the memory object represented by +.IR fildes . +.P +If +.IR fildes +represents a typed memory object opened with either the +POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG +flag, the memory object to be mapped +shall be that portion of the typed memory object allocated by the +implementation as specified below. In this case, if +.IR off +is non-zero, the behavior of +\fImmap\fR() +is undefined. If +.IR fildes +refers to a valid typed memory object that is not accessible from the +calling process, +\fImmap\fR() +shall fail. +.P +The mapping established by +\fImmap\fR() +shall replace any previous mappings for those whole pages containing +any part of the address space of the process starting at +.IR pa +and continuing for +.IR len +bytes. +.P +If the size of the mapped file changes after the call to +\fImmap\fR() +as a result of some other operation on the mapped file, the effect of +references to portions of the mapped region that correspond to added or +removed portions of the file is unspecified. +.P +If +.IR len +is zero, +\fImmap\fR() +shall fail and no mapping shall be established. +.P +The parameter +.IR prot +determines whether read, write, execute, or some combination of +accesses are permitted to the data being mapped. The +.IR prot +shall be either PROT_NONE +or the bitwise-inclusive OR of one or more of the other flags in +the following table, defined in the +.IR +header. +.TS +center box tab(!); +cB | cB +lw(1.5i) | lw(2i). +Symbolic Constant!Description +_ +PROT_READ!Data can be read. +PROT_WRITE!Data can be written. +PROT_EXEC!Data can be executed. +PROT_NONE!Data cannot be accessed. +.TE +.P +If an implementation cannot support the combination of access types +specified by +.IR prot , +the call to +\fImmap\fR() +shall fail. +.P +An implementation may permit accesses other than those specified by +.IR prot ; +however, the implementation shall not permit a write to succeed +where PROT_WRITE has not been set and shall not permit any access where +PROT_NONE alone has been set. The implementation shall support at least +the following values of +.IR prot : +PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of +PROT_READ and PROT_WRITE. The file descriptor +.IR fildes +shall have been opened with read permission, regardless of the +protection options specified. If PROT_WRITE is specified, the +application shall ensure that it has opened the file descriptor +.IR fildes +with write permission unless MAP_PRIVATE is specified in the +.IR flags +parameter as described below. +.P +The parameter +.IR flags +provides other information about the handling of the mapped data. +The value of +.IR flags +is the bitwise-inclusive OR of these options, defined in +.IR : +.TS +center box tab(!); +cB | cB +lw(1.5i) | lw(2i). +Symbolic Constant!Description +_ +MAP_SHARED!Changes are shared. +MAP_PRIVATE!Changes are private. +MAP_FIXED!Interpret \fIaddr\fP exactly. +.TE +.P +It is implementation-defined whether MAP_FIXED shall be supported. +MAP_FIXED shall be supported on XSI-conformant systems. +.P +MAP_SHARED and MAP_PRIVATE describe the disposition of write references +to the memory object. If MAP_SHARED is specified, write references +shall change the underlying object. If MAP_PRIVATE is specified, +modifications to the mapped data by the calling process shall be visible +only to the calling process and shall not change the underlying object. +It is unspecified whether modifications to the underlying object done +after the MAP_PRIVATE mapping is established are visible through the +MAP_PRIVATE mapping. Either MAP_SHARED or MAP_PRIVATE can be +specified, but not both. The mapping type is retained across +\fIfork\fR(). +.P +The state of synchronization objects such as mutexes, semaphores, +barriers, and conditional variables placed in shared memory mapped with +MAP_SHARED becomes undefined when the last region in any process +containing the synchronization object is unmapped. +.P +When +.IR fildes +represents a typed memory object opened with either the +POSIX_TYPED_MEM_ALLOCATE flag or the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, +\fImmap\fR() +shall, if there are enough resources available, map +.IR len +bytes allocated from the corresponding typed memory object which were +not previously allocated to any process in any processor that may +access that typed memory object. If there are not enough resources +available, the function shall fail. If +.IR fildes +represents a typed memory object opened with the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be +contiguous within the typed memory object. If +.IR fildes +represents a typed memory object opened with the +POSIX_TYPED_MEM_ALLOCATE flag, these allocated bytes may be composed of +non-contiguous fragments within the typed memory object. If +.IR fildes +represents a typed memory object opened with neither the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the POSIX_TYPED_MEM_ALLOCATE +flag, +.IR len +bytes starting at offset +.IR off +within the typed memory object are mapped, exactly as when mapping a +file or shared memory object. In this case, if two processes map an +area of typed memory using the same +.IR off +and +.IR len +values and using file descriptors that refer to the same memory pool +(either from the same port or from a different port), both processes +shall map the same region of storage. +.P +When MAP_FIXED is set in the +.IR flags +argument, the implementation is informed that the value of +.IR pa +shall be +.IR addr , +exactly. If MAP_FIXED is set, +\fImmap\fR() +may return MAP_FAILED and set +.IR errno +to +.BR [EINVAL] . +If a MAP_FIXED request is successful, then any previous mappings +or memory locks +for those whole pages containing any part of the address range +[\fIpa\fP,\fIpa\fP+\fIlen\fR) shall be removed, as if by an +appropriate call to +\fImunmap\fR(), +before the new mapping is established. +.P +When MAP_FIXED is not set, the implementation uses +.IR addr +in an implementation-defined manner to arrive at +.IR pa . +The +.IR pa +so chosen shall be an area of the address space that the implementation +deems suitable for a mapping of +.IR len +bytes to the file. All implementations interpret an +.IR addr +value of 0 as granting the implementation complete freedom in selecting +.IR pa , +subject to constraints described below. A non-zero value of +.IR addr +is taken to be a suggestion of a process address near which the mapping +should be placed. When the implementation selects a value for +.IR pa , +it never places a mapping at address 0, nor does it replace any extant +mapping. +.P +If MAP_FIXED is specified and +.IR addr +is non-zero, it shall have the same remainder as the +.IR off +parameter, modulo the page size as returned by +\fIsysconf\fR() +when passed _SC_PAGESIZE or _SC_PAGE_SIZE. The implementation may +require that off is a multiple of the page size. If MAP_FIXED is +specified, the implementation may require that +.IR addr +is a multiple of the page size. The system performs mapping operations +over whole pages. Thus, while the parameter +.IR len +need not meet a size or alignment constraint, the system shall include, +in any mapping operation, any partial page specified by the address +range starting at +.IR pa +and continuing for +.IR len +bytes. +.P +The system shall always zero-fill any partial page at the end of an +object. Further, the system shall never write out any modified +portions of the last page of an object which are beyond its end. +References within the address range starting at +.IR pa +and continuing for +.IR len +bytes to whole pages following the end of an object shall result in +delivery of a SIGBUS signal. +.P +An implementation may generate SIGBUS signals when a reference would +cause an error in the mapped object, such as out-of-space condition. +.P +The +\fImmap\fR() +function shall add an extra reference to the file associated with the +file descriptor +.IR fildes +which is not removed by a subsequent +\fIclose\fR() +on that file descriptor. This reference shall be removed when there are +no more mappings to the file. +.P +The last data access timestamp of the mapped file may be marked for +update at any time between the +\fImmap\fR() +call and the corresponding +\fImunmap\fR() +call. The initial read or write reference to a mapped region shall cause +the file's last data access timestamp to be marked for update if it has +not already been marked for update. +.P +The last data modification and last file status change timestamps +of a file that is mapped with MAP_SHARED and PROT_WRITE shall be +marked +for update at some point in the interval between a write reference to +the mapped region and the next call to +\fImsync\fR() +with MS_ASYNC or MS_SYNC for that portion of the file by any process. +If there is no such call and if the underlying file is modified +as a result of a write reference, then these timestamps shall be marked +for update at some time after the write reference. +.P +There may be implementation-defined limits on the number of memory +regions that can be mapped (per process or per system). +.P +If such a limit is imposed, whether the number of memory regions that +can be mapped by a process is decreased by the use of +\fIshmat\fR() +is implementation-defined. +.P +If +\fImmap\fR() +fails for reasons other than +.BR [EBADF] , +.BR [EINVAL] , +or +.BR [ENOTSUP] , +some of the mappings in the address range starting at +.IR addr +and continuing for +.IR len +bytes may have been unmapped. +.SH "RETURN VALUE" +Upon successful completion, the +\fImmap\fR() +function shall return the address at which the mapping was placed (\c +.IR pa ); +otherwise, it shall return a value of MAP_FAILED and set +.IR errno +to indicate the error. The symbol MAP_FAILED is defined in the +.IR +header. No successful return from +\fImmap\fR() +shall return the value MAP_FAILED. +.SH ERRORS +The +\fImmap\fR() +function shall fail if: +.TP +.BR EACCES +The +.IR fildes +argument is not open for read, regardless of the protection specified, +or +.IR fildes +is not open for write and PROT_WRITE was specified for a MAP_SHARED +type mapping. +.TP +.BR EAGAIN +The mapping could not be locked in memory, if required by +\fImlockall\fR(), +due to a lack of resources. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR EINVAL +The value of +.IR len +is zero. +.TP +.BR EINVAL +The value of +.IR flags +is invalid (neither MAP_PRIVATE nor MAP_SHARED is set). +.TP +.BR EMFILE +The number of mapped regions would exceed an implementation-defined +limit (per process or per system). +.TP +.BR ENODEV +The +.IR fildes +argument refers to a file whose type is not supported by +\fImmap\fR(). +.TP +.BR ENOMEM +MAP_FIXED was specified, and the range +[\fIaddr\fP,\fIaddr\fP+\fIlen\fR) exceeds that allowed for the +address space of a process; or, if MAP_FIXED was not specified and +there is insufficient room in the address space to effect the mapping. +.TP +.BR ENOMEM +The mapping could not be locked in memory, if required by +\fImlockall\fR(), +because it would require more space than the system is able to supply. +.TP +.BR ENOMEM +Not enough unallocated memory resources remain in the typed memory +object designated by +.IR fildes +to allocate +.IR len +bytes. +.TP +.BR ENOTSUP +MAP_FIXED or MAP_PRIVATE was specified in the +.IR flags +argument and the implementation does not support this functionality. +.RS 12 +.P +The implementation does not support the combination of accesses +requested in the +.IR prot +argument. +.RE +.TP +.BR ENXIO +Addresses in the range [\fIoff\fP,\fIoff\fP+\fIlen\fR) are invalid +for the object specified by +.IR fildes . +.TP +.BR ENXIO +MAP_FIXED was specified in +.IR flags +and the combination of +.IR addr , +.IR len , +and +.IR off +is invalid for the object specified by +.IR fildes . +.TP +.BR ENXIO +The +.IR fildes +argument refers to a typed memory object that is not accessible from +the calling process. +.TP +.BR EOVERFLOW +The file is a regular file and the value of +.IR off +plus +.IR len +exceeds the offset maximum established in the open file description +associated with +.IR fildes . +.br +.P +The +\fImmap\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR addr +argument (if MAP_FIXED was specified) or +.IR off +is not a multiple of the page size as returned by +\fIsysconf\fR(), +or is considered invalid by the implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Use of +\fImmap\fR() +may reduce the amount of memory available to other memory allocation +functions. +.P +Use of MAP_FIXED may result in unspecified behavior in further use of +\fImalloc\fR() +and +\fIshmat\fR(). +The use of MAP_FIXED is discouraged, as it may prevent an +implementation from making the most effective use of resources. Most +implementations require that +.IR off +and +.IR addr +are multiples of the page size as returned by +\fIsysconf\fR(). +.P +The application must ensure correct synchronization when using +\fImmap\fR() +in conjunction with any other file access method, such as +\fIread\fR() +and +\fIwrite\fR(), +standard input/output, and +\fIshmat\fR(). +.P +The +\fImmap\fR() +function allows access to resources via address space manipulations, +instead of +\fIread\fR()/\c +\fIwrite\fR(). +Once a file is mapped, all a process has to do to access it is use the +data at the address to which the file was mapped. So, using +pseudo-code to illustrate the way in which an existing program might be +changed to use +\fImmap\fR(), +the following: +.sp +.RS 4 +.nf + +fildes = open(...) +lseek(fildes, some_offset) +read(fildes, buf, len) +/* Use data in buf. */ +.fi +.P +.RE +.P +becomes: +.sp +.RS 4 +.nf + +fildes = open(...) +address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) +/* Use data at address. */ +.fi +.P +.RE +.SH RATIONALE +After considering several other alternatives, it was decided to adopt +the +\fImmap\fR() +definition found in SVR4 for mapping memory objects into process +address spaces. The SVR4 definition is minimal, in that it describes +only what has been built, and what appears to be necessary for a +general and portable mapping facility. +.P +Note that while +\fImmap\fR() +was first designed for mapping files, it is actually a general-purpose +mapping facility. It can be used to map any appropriate object, such +as memory, files, devices, and so on, into the address space of a +process. +.P +When a mapping is established, it is possible that the implementation +may need to map more than is requested into the address space of the +process because of hardware requirements. An application, however, +cannot count on this behavior. Implementations that do not use a paged +architecture may simply allocate a common memory region and return the +address of it; such implementations probably do not allocate any more +than is necessary. References past the end of the requested area are +unspecified. +.P +If an application requests a mapping that overlaps existing mappings +in the process, it might be desirable that an implementation detect +this and inform the application. However, if the program specifies a +fixed address mapping (which requires some implementation knowledge to +determine a suitable address, if the function is supported at all), +then the program is presumed to be successfully managing its own +address space and should be trusted when it asks to map over existing +data structures. Furthermore, it is also desirable to make as few +system calls as possible, and it might be considered onerous to +require an +\fImunmap\fR() +before an +\fImmap\fR() +to the same address range. This volume of POSIX.1\(hy2017 specifies that the new mapping +replaces any existing mappings (implying an automatic +\fImunmap\fR() +on the address range), following existing practice in this regard. +The standard developers also considered whether there should be a way +for new mappings to overlay existing mappings, but found no existing +practice for this. +.P +It is not expected that all hardware implementations are able to +support all combinations of permissions at all addresses. +Implementations are required to disallow write +access to mappings without write permission and to disallow access to +mappings without any access permission. Other than these restrictions, +implementations may allow access types other than those requested by +the application. For example, if the application requests only +PROT_WRITE, the implementation may also allow read access. A call to +\fImmap\fR() +fails if the implementation cannot support allowing all the access +requested by the application. For example, some implementations +cannot support a request for both write access and execute access +simultaneously. All implementations must support requests for no access, +read access, write access, and both read and write access. Strictly +conforming code must only rely on the required checks. These restrictions +allow for portability across a wide range of hardware. +.P +The MAP_FIXED address treatment is likely to fail for non-page-aligned +values and for certain architecture-dependent address ranges. +Conforming implementations cannot count on being able to choose address +values for MAP_FIXED without utilizing non-portable, +implementation-defined knowledge. Nonetheless, MAP_FIXED is provided +as a standard interface conforming to existing practice for utilizing +such knowledge when it is available. +.P +Similarly, in order to allow implementations that do not support +virtual addresses, support for directly specifying any mapping +addresses via MAP_FIXED is not required and thus a conforming +application may not count on it. +.P +The MAP_PRIVATE +function can be implemented efficiently when memory protection hardware +is available. When such hardware is not available, implementations can +implement such ``mappings'' +by simply making a real copy of the relevant data into process private +memory, though this tends to behave similarly to +\fIread\fR(). +.P +The function has been defined to allow for many different models of +using shared memory. However, all uses are not equally portable across +all machine architectures. In particular, the +\fImmap\fR() +function allows the system as well as the application to specify the +address at which to map a specific region of a memory object. The most +portable way to use the function is always to let the system choose +the address, specifying NULL as the value for the argument +.IR addr +and not to specify MAP_FIXED. +.P +If it is intended that a particular region of a memory object be mapped +at the same address in a group of processes (on machines where this is +even possible), then MAP_FIXED can be used to pass in the desired +mapping address. The system can still be used to choose the desired +address if the first such mapping is made without specifying MAP_FIXED, +and then the resulting mapping address can be passed to subsequent +processes for them to pass in via MAP_FIXED. The availability of a +specific address range cannot be guaranteed, in general. +.P +The +\fImmap\fR() +function can be used to map a region of memory that is larger than the +current size of the object. Memory access within the mapping but +beyond the current end of the underlying objects may result in SIGBUS +signals being sent to the process. The reason for this is that the +size of the object can be manipulated by other processes and can change +at any moment. The implementation should tell the application that a +memory reference is outside the object where this can be detected; +otherwise, written data may be lost and read data may not reflect +actual data in the object. +.P +Note that references beyond the end of the object do not extend the +object as the new end cannot be determined precisely by most virtual +memory hardware. Instead, the size can be directly manipulated by +\fIftruncate\fR(). +.P +Process memory locking does apply to shared memory regions, and the +MCL_FUTURE argument to +\fImlockall\fR() +can be relied upon to cause new shared memory regions to be +automatically locked. +.P +Existing implementations of +\fImmap\fR() +return the value \-1 when unsuccessful. Since the casting of this +value to type +.BR "void *" +cannot be guaranteed by the ISO\ C standard to be distinct from a successful +value, this volume of POSIX.1\(hy2017 defines the symbol MAP_FAILED, +which a conforming implementation does not return as the result of a +successful call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIlockf\fR\^(\|)", +.IR "\fImsync\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fImprotect\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/modf.3p b/upstream/archlinux/man3p/modf.3p new file mode 100644 index 00000000..d1c332c8 --- /dev/null +++ b/upstream/archlinux/man3p/modf.3p @@ -0,0 +1,109 @@ +'\" et +.TH MODF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +modf, +modff, +modfl +\(em decompose a floating-point number +.SH SYNOPSIS +.LP +.nf +#include +.P +double modf(double \fIx\fP, double *\fIiptr\fP); +float modff(float \fIvalue\fP, float *\fIiptr\fP); +long double modfl(long double \fIvalue\fP, long double *\fIiptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall break the argument +.IR x +into integral and fractional parts, each of which has the same sign as +the argument. It stores the integral part as a +.BR double +(for the +\fImodf\fR() +function), a +.BR float +(for the +\fImodff\fR() +function), or a +.BR "long double" +(for the +\fImodfl\fR() +function), in the object pointed to by +.IR iptr . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the signed +fractional part of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned, and *\fIiptr\fP shall be set to a +NaN. +.P +If +.IR x +is \(+-Inf, \(+-0 shall be returned, and *\fIiptr\fP shall be set to +\(+-Inf. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImodf\fR() +function computes the function result and *\fIiptr\fP such that: +.sp +.RS 4 +.nf + +a = modf(x, iptr) ; +x == a+*iptr ; +.fi +.P +.RE +.P +allowing for the usual floating-point inaccuracies. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfrexp\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIldexp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mprotect.3p b/upstream/archlinux/man3p/mprotect.3p new file mode 100644 index 00000000..8b668fd0 --- /dev/null +++ b/upstream/archlinux/man3p/mprotect.3p @@ -0,0 +1,160 @@ +'\" et +.TH MPROTECT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mprotect +\(em set protection of memory mapping +.SH SYNOPSIS +.LP +.nf +#include +.P +int mprotect(void *\fIaddr\fP, size_t \fIlen\fP, int \fIprot\fP); +.fi +.SH DESCRIPTION +The +\fImprotect\fR() +function shall change the access protections to be that specified by +.IR prot +for those whole pages containing any part of the address space of the +process starting at address +.IR addr +and continuing for +.IR len +bytes. The parameter +.IR prot +determines whether read, write, execute, or some combination of +accesses are permitted to the data being mapped. The +.IR prot +argument should be either PROT_NONE or the bitwise-inclusive OR of one +or more of PROT_READ, PROT_WRITE, and PROT_EXEC. +.P +If an implementation cannot support the combination of access types +specified by +.IR prot , +the call to +\fImprotect\fR() +shall fail. +.P +An implementation may permit accesses other than those specified by +.IR prot ; +however, no implementation shall permit a write to succeed where +PROT_WRITE has not been set or shall permit any access where PROT_NONE +alone has been set. Implementations shall support at least the +following values of +.IR prot : +PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of +PROT_READ and PROT_WRITE. If PROT_WRITE is specified, the application +shall ensure that it has opened the mapped objects in the specified +address range with write permission, unless MAP_PRIVATE +was specified in the original mapping, regardless of whether the file +descriptors used to map the objects have since been closed. +.P +The implementation may require that +.IR addr +be a multiple of the page size as returned by +\fIsysconf\fR(). +.P +The behavior of this function is unspecified if the mapping was not +established by a call to +\fImmap\fR(). +.P +When +\fImprotect\fR() +fails for reasons other than +.BR [EINVAL] , +the protections on some of the pages in the range +[\fIaddr\fP,\fIaddr\fP+\fIlen\fR) may have been changed. +.SH "RETURN VALUE" +Upon successful completion, +\fImprotect\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImprotect\fR() +function shall fail if: +.TP +.BR EACCES +The +.IR prot +argument specifies a protection that violates the access permission the +process has to the underlying memory object. +.TP +.BR EAGAIN +The +.IR prot +argument specifies PROT_WRITE over a MAP_PRIVATE mapping and there are +insufficient memory resources to reserve for locking the private page. +.TP +.BR ENOMEM +Addresses in the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fR) are invalid +for the address space of a process, or specify one or more pages which +are not mapped. +.TP +.BR ENOMEM +The +.IR prot +argument specifies PROT_WRITE on a MAP_PRIVATE mapping, and it would +require more space than the system is able to supply for locking the +private pages, if required. +.TP +.BR ENOTSUP +The implementation does not support the combination of accesses +requested in the +.IR prot +argument. +.P +The +\fImprotect\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR addr +argument is not a multiple of the page size as returned by +\fIsysconf\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Most implementations require that +.IR addr +is a multiple of the page size as returned by +\fIsysconf\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_close.3p b/upstream/archlinux/man3p/mq_close.3p new file mode 100644 index 00000000..d1e13a6e --- /dev/null +++ b/upstream/archlinux/man3p/mq_close.3p @@ -0,0 +1,92 @@ +'\" et +.TH MQ_CLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_close +\(em close a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_close(mqd_t \fImqdes\fP); +.fi +.SH DESCRIPTION +The +\fImq_close\fR() +function shall remove the association between the message queue +descriptor, +.IR mqdes , +and its message queue. The results of using this message queue +descriptor after successful return from this +\fImq_close\fR(), +and until the return of this message queue descriptor from a subsequent +\fImq_open\fR(), +are undefined. +.P +If the process has successfully attached a notification request to the +message queue via this +.IR mqdes , +this attachment shall be removed, and the message queue is available +for another process to attach for notification. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_close\fR() +function shall return a value of zero; otherwise, the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_close\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_getattr.3p b/upstream/archlinux/man3p/mq_getattr.3p new file mode 100644 index 00000000..9f1a2c30 --- /dev/null +++ b/upstream/archlinux/man3p/mq_getattr.3p @@ -0,0 +1,113 @@ +'\" et +.TH MQ_GETATTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_getattr +\(em get message queue attributes +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_getattr(mqd_t \fImqdes\fP, struct mq_attr *\fImqstat\fP); +.fi +.SH DESCRIPTION +The +\fImq_getattr\fR() +function shall obtain status information and attributes of the message +queue and the open message queue description associated with the +message queue descriptor. +.P +The +.IR mqdes +argument specifies a message queue descriptor. +.P +The results shall be returned in the +.BR mq_attr +structure referenced by the +.IR mqstat +argument. +.P +Upon return, the following members shall have the values associated +with the open message queue description as set when the message queue +was opened and as modified by subsequent +\fImq_setattr\fR() +calls: +.IR mq_flags . +.P +The following attributes of the message queue shall be returned as set +at message queue creation: +.IR mq_maxmsg , +.IR mq_msgsize . +.P +Upon return, the following members within the +.BR mq_attr +structure referenced by the +.IR mqstat +argument shall be set to the current state of the message queue: +.IP "\fImq_curmsgs\fP" 10 +The number of messages currently on the queue. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_getattr\fR() +function shall return zero. Otherwise, the function shall return +\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_getattr\fR() +function may fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +See +.IR "\fImq_notify\fR\^(\|)". +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_notify.3p b/upstream/archlinux/man3p/mq_notify.3p new file mode 100644 index 00000000..333ad1c6 --- /dev/null +++ b/upstream/archlinux/man3p/mq_notify.3p @@ -0,0 +1,198 @@ +'\" et +.TH MQ_NOTIFY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_notify +\(em notify process that a message is available +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_notify(mqd_t \fImqdes\fP, const struct sigevent *\fInotification\fP); +.fi +.SH DESCRIPTION +If the argument +.IR notification +is not NULL, this function shall register the calling process to be +notified of message arrival at an empty message queue associated with +the specified message queue descriptor, +.IR mqdes . +The notification specified by the +.IR notification +argument shall 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 shall fail. +.P +If +.IR notification +is NULL and the process is currently registered for notification by the +specified message queue, the existing registration shall be removed. +.P +When the notification is sent to the registered process, its +registration shall be removed. The message queue shall then be available +for registration. +.P +If a process has registered for notification of message arrival at a +message queue and some thread is blocked in +\fImq_receive\fR() +or +\fImq_timedreceive\fR() +waiting to receive a message when a message arrives at the queue, the +arriving message shall satisfy the appropriate +\fImq_receive\fR() +or +\fImq_timedreceive\fR(), +respectively. The resulting behavior is as if the message queue remains +empty, and no notification shall be sent. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_notify\fR() +function shall return a value of zero; otherwise, the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_notify\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.TP +.BR EBUSY +A process is already registered for notification by the message queue. +.P +The +\fImq_notify\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR notification +argument is NULL and the process is currently not registered. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following program registers a notification request for the message +queue named in its command-line argument. Notification is performed +by creating a thread. The thread executes a function which reads one +message from the queue and then terminates the process. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +.P +static void /* Thread start function */ +tfunc(union sigval sv) +{ + struct mq_attr attr; + ssize_t nr; + void *buf; + mqd_t mqdes = *((mqd_t *) sv.sival_ptr); +.P + /* Determine maximum msg size; allocate buffer to receive msg */ +.P + if (mq_getattr(mqdes, &attr) == -1) { + perror("mq_getattr"); + exit(EXIT_FAILURE); + } + buf = malloc(attr.mq_msgsize); +.P + if (buf == NULL) { + perror("malloc"); + exit(EXIT_FAILURE); + } +.P + nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL); + if (nr == -1) { + perror("mq_receive"); + exit(EXIT_FAILURE); + } +.P + printf("Read %ld bytes from message queue\en", (long) nr); + free(buf); + exit(EXIT_SUCCESS); /* Terminate the process */ +} +.P +int +main(int argc, char *argv[]) +{ + mqd_t mqdes; + struct sigevent not; +.P + assert(argc == 2); +.P + mqdes = mq_open(argv[1], O_RDONLY); + if (mqdes == (mqd_t) -1) { + perror("mq_open"); + exit(EXIT_FAILURE); + } +.P + not.sigev_notify = SIGEV_THREAD; + not.sigev_notify_function = tfunc; + not.sigev_notify_attributes = NULL; + not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */ + if (mq_notify(mqdes, ¬) == -1) { + perror("mq_notify"); + exit(EXIT_FAILURE); + } +.P + pause(); /* Process will be terminated by thread function */ +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_open.3p b/upstream/archlinux/man3p/mq_open.3p new file mode 100644 index 00000000..8b1765dd --- /dev/null +++ b/upstream/archlinux/man3p/mq_open.3p @@ -0,0 +1,319 @@ +'\" et +.TH MQ_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_open +\(em open a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +mqd_t mq_open(const char *\fIname\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +The +\fImq_open\fR() +function shall establish the connection between a process and a message +queue with a message queue descriptor. It shall create 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 +.IR name +argument points to a string naming a message queue. It is unspecified +whether the name appears in the file system and is visible to other +functions that take pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except that +the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as the +pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fImq_open\fR() +with the same value of +.IR name +shall refer to the same message queue object, as long as that name +has not been removed. If +.IR name +does not begin with the + +character, the effect is implementation-defined. If the +.IR name +argument is not the name of an existing message queue and creation is +not requested, +\fImq_open\fR() +shall fail and return an error. +.P +A message queue descriptor may be implemented using a file +descriptor, in which case applications can open up to at least +{OPEN_MAX} +file and message queues. +.P +The +.IR oflag +argument requests the desired receive and/or send access to the message +queue. The requested access permission to receive messages or send +messages shall be granted if the calling process would be granted read +or write access, respectively, to an equivalently protected file. +.P +The value of +.IR oflag +is the bitwise-inclusive OR of values from the following list. +Applications shall specify exactly one of the first three values +(access modes) below in the value of +.IR oflag : +.IP O_RDONLY 12 +Open the message queue for receiving messages. The process can use the +returned message queue descriptor with +\fImq_receive\fR(), +but not +\fImq_send\fR(). +A message queue may be open multiple times in the same or different +processes for receiving messages. +.IP O_WRONLY 12 +Open the queue for sending messages. The process can use the returned +message queue descriptor with +\fImq_send\fR() +but not +\fImq_receive\fR(). +A message queue may be open multiple times in the same or different +processes for sending messages. +.IP O_RDWR 12 +Open the queue for both receiving and sending messages. The process +can use any of the functions allowed for O_RDONLY and O_WRONLY. A +message queue may be open multiple times in the same or different +processes for sending messages. +.P +Any combination of the remaining flags may be specified in the value of +.IR oflag : +.IP O_CREAT 12 +Create a message queue. It requires two additional arguments: +.IR mode , +which shall be of type +.BR mode_t , +and +.IR attr , +which shall be a pointer to an +.BR mq_attr +structure. If the pathname +.IR name +has already been used to create a message queue that still exists, then +this flag shall have no effect, except as noted under O_EXCL. +Otherwise, a message queue shall be created without any messages in +it. The user ID of the message queue shall be set to the effective +user ID of the process. The group ID of the message queue shall be +set to the effective group ID of the process; however, if the +.IR name +argument is visible in the file system, the group ID may be set +to the group ID of the containing directory. When bits in +.IR mode +other than the file permission bits are specified, the effect is +unspecified. If +.IR attr +is NULL, the message queue shall be created with implementation-defined +default message queue attributes. If +.IR attr +is non-NULL and the calling process has appropriate privileges on +.IR name , +the message queue +.IR mq_maxmsg +and +.IR mq_msgsize +attributes shall be set to the values of the corresponding members in the +.BR mq_attr +structure referred to by +.IR attr . +The values of the +.IR mq_flags +and +.IR mq_curmsgs +members of the +.BR mq_attr +structure shall be ignored. If +.IR attr +is non-NULL, but the calling process does not have appropriate +privileges on +.IR name , +the +\fImq_open\fR() +function shall fail and return an error without creating the message +queue. +.IP O_EXCL 12 +If O_EXCL and O_CREAT are set, +\fImq_open\fR() +shall fail if the message queue +.IR name +exists. The check for the existence of the message queue and the +creation of the message queue if it does not exist shall be atomic with +respect to other threads executing +\fImq_open\fR() +naming the same +.IR name +with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, +the result is undefined. +.IP O_NONBLOCK 12 +Determines whether an +\fImq_send\fR() +or +\fImq_receive\fR() +waits for resources or messages that are not currently available, or +fails with +.IR errno +set to +.BR [EAGAIN] ; +see +.IR "\fImq_send\fR\^(\|)" +and +.IR "\fImq_receive\fR\^(\|)" +for details. +.P +The +\fImq_open\fR() +function does not add or remove messages from the queue. +.SH "RETURN VALUE" +Upon successful completion, the function shall return a message queue +descriptor; otherwise, the function shall return (\fBmqd_t\fP)\-1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_open\fR() +function shall fail if: +.TP +.BR EACCES +The message queue exists and the permissions specified by +.IR oflag +are denied, or the message queue does not exist and permission to +create the message queue is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set and the named message queue already exists. +.TP +.BR EINTR +The +\fImq_open\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +\fImq_open\fR() +function is not supported for the given name. +.TP +.BR EINVAL +O_CREAT was specified in +.IR oflag , +the value of +.IR attr +is not NULL, and either +.IR mq_maxmsg +or +.IR mq_msgsize +was less than or equal to zero. +.TP +.BR EMFILE +Too many message queue descriptors or file descriptors are currently in +use by this process. +.TP +.BR ENFILE +Too many message queues are currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and the named message queue does not exist. +.TP +.BR ENOSPC +There is insufficient space for the creation of the new message queue. +.br +.P +If any of the following conditions occur, the +\fImq_open\fR() +function may return (\c +.BR mqd_t )\-1 +and set +.IR errno +to the corresponding value. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fImq_open\fR() +and +\fImq_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_receive.3p b/upstream/archlinux/man3p/mq_receive.3p new file mode 100644 index 00000000..426f7233 --- /dev/null +++ b/upstream/archlinux/man3p/mq_receive.3p @@ -0,0 +1,203 @@ +'\" et +.TH MQ_RECEIVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_receive, +mq_timedreceive +\(em receive a message from a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t mq_receive(mqd_t \fImqdes\fP, char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned *\fImsg_prio\fP); +.P +#include +#include +.P +ssize_t mq_timedreceive(mqd_t \fImqdes\fP, char *restrict \fImsg_ptr\fP, + size_t \fImsg_len\fP, unsigned *restrict \fImsg_prio\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fImq_receive\fR() +function shall receive the oldest of the highest priority +message(s) from the message queue specified by +.IR mqdes . +If the size of the buffer in bytes, specified by the +.IR msg_len +argument, is less than the +.IR mq_msgsize +attribute of the message queue, the function shall fail and return an +error. Otherwise, the selected message shall be removed from the queue +and copied to the buffer pointed to by the +.IR msg_ptr +argument. +.P +If the value of +.IR msg_len +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +If the argument +.IR msg_prio +is not NULL, the priority of the selected message shall be stored in the +location referenced by +.IR msg_prio . +.P +If the specified message queue is empty and O_NONBLOCK +is not set in the message queue description associated with +.IR mqdes , +\fImq_receive\fR() +shall block until a message is enqueued on the message queue or until +\fImq_receive\fR() +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 shall be selected to receive +the message. Otherwise, it is unspecified which waiting thread receives +the message. If the specified message queue is empty and O_NONBLOCK is +set in the message queue description associated with +.IR mqdes , +no message shall be removed from the queue, and +\fImq_receive\fR() +shall return an error. +.P +The +\fImq_timedreceive\fR() +function shall receive the oldest of the highest priority messages +from the message queue specified by +.IR mqdes +as described for the +\fImq_receive\fR() +function. However, if O_NONBLOCK was not specified when the message +queue was opened via the +\fImq_open\fR() +function, and no message exists on the queue to satisfy the receive, +the wait for such a message shall be terminated when the specified +timeout expires. If O_NONBLOCK is set, this function is equivalent to +\fImq_receive\fR(). +.P +The timeout expires when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock on +which it is based. The +.IR timespec +argument is defined in the +.IR +header. +.P +Under no circumstance shall the operation fail with a timeout if a +message can be removed from the message queue immediately. The validity +of the +.IR abstime +parameter need not be checked if a message can be removed from the +message queue immediately. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_receive\fR() +and +\fImq_timedreceive\fR() +functions shall return the length of the selected message in bytes and +the message shall be removed from the queue. Otherwise, no message +shall be removed from the queue, the functions shall return a value of +\-1, and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EAGAIN +O_NONBLOCK was set in the message description associated with +.IR mqdes , +and the specified message queue is empty. +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor open for reading. +.TP +.BR EMSGSIZE +The specified message buffer size, +.IR msg_len , +is less than the message size attribute of the message queue. +.TP +.BR EINTR +The +\fImq_receive\fR() +or +\fImq_timedreceive\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR ETIMEDOUT +The O_NONBLOCK flag was not set when the message queue was opened, but +no message arrived on the queue before the specified timeout expired. +.P +These functions may fail if: +.TP +.BR EBADMSG +The implementation has detected a data corruption problem with the +message. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_send.3p b/upstream/archlinux/man3p/mq_send.3p new file mode 100644 index 00000000..f9a16da5 --- /dev/null +++ b/upstream/archlinux/man3p/mq_send.3p @@ -0,0 +1,212 @@ +'\" et +.TH MQ_SEND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_send, +mq_timedsend +\(em send a message to a message queue (\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_send(mqd_t \fImqdes\fP, const char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned \fImsg_prio\fP); +.P +#include +#include +.P +int mq_timedsend(mqd_t \fImqdes\fP, const char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned \fImsg_prio\fP, const struct timespec *\fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fImq_send\fR() +function shall add the message pointed to by the argument +.IR msg_ptr +to the message queue specified by +.IR mqdes . +The +.IR msg_len +argument specifies the length of the message, in bytes, pointed to by +.IR msg_ptr . +The value of +.IR msg_len +shall be less than or equal to the +.IR mq_msgsize +attribute of the message queue, or +\fImq_send\fR() +shall fail. +.P +If the specified message queue is not full, +\fImq_send\fR() +shall behave as if the message is inserted into the message queue at +the position indicated by the +.IR msg_prio +argument. A message with a larger numeric value of +.IR msg_prio +shall be inserted before messages with lower values of +.IR msg_prio . +A message shall be inserted after other messages in the queue, if any, +with equal +.IR msg_prio . +The value of +.IR msg_prio +shall be less than +{MQ_PRIO_MAX}. +.P +If the specified message queue is full and O_NONBLOCK +is not set in the message queue description associated with +.IR mqdes , +\fImq_send\fR() +shall block until space becomes available to enqueue the message, or +until +\fImq_send\fR() +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 shall be unblocked to send its +message. Otherwise, it is unspecified which waiting thread is +unblocked. If the specified message queue is full and O_NONBLOCK is +set in the message queue description associated with +.IR mqdes , +the message shall not be queued and +\fImq_send\fR() +shall return an error. +.P +The +\fImq_timedsend\fR() +function shall add a message to the message queue specified by +.IR mqdes +in the manner defined for the +\fImq_send\fR() +function. However, if the specified message queue is full and +O_NONBLOCK is not set in the message queue description associated with +.IR mqdes , +the wait for sufficient room in the queue shall be terminated when the +specified timeout expires. If O_NONBLOCK is set in the message queue +description, this function shall be equivalent to +\fImq_send\fR(). +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock on +which it is based. The +.IR timespec +argument is defined in the +.IR +header. +.P +Under no circumstance shall the operation fail with a timeout if there +is sufficient room in the queue to add the message immediately. The +validity of the +.IR abstime +parameter need not be checked when there is sufficient room in the +queue. +.SH "RETURN VALUE" +Upon successful completion, the +\fImq_send\fR() +and +\fImq_timedsend\fR() +functions shall return a value of zero. Otherwise, no message shall be +enqueued, the functions shall return \-1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fImq_send\fR() +and +\fImq_timedsend\fR() +functions shall fail if: +.TP +.BR EAGAIN +The O_NONBLOCK flag is set in the message queue description associated +with +.IR mqdes , +and the specified message queue is full. +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor open for writing. +.TP +.BR EINTR +A signal interrupted the call to +\fImq_send\fR() +or +\fImq_timedsend\fR(). +.TP +.BR EINVAL +The value of +.IR msg_prio +was outside the valid range. +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR EMSGSIZE +The specified message length, +.IR msg_len , +exceeds the message size attribute of the message queue. +.TP +.BR ETIMEDOUT +The 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. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The value of the symbol +{MQ_PRIO_MAX} +limits the number of priority levels supported by the application. +Message priorities range from 0 to +{MQ_PRIO_MAX}\-1. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_setattr.3p b/upstream/archlinux/man3p/mq_setattr.3p new file mode 100644 index 00000000..0d72c645 --- /dev/null +++ b/upstream/archlinux/man3p/mq_setattr.3p @@ -0,0 +1,114 @@ +'\" et +.TH MQ_SETATTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_setattr +\(em set message queue attributes +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_setattr(mqd_t \fImqdes\fP, const struct mq_attr *restrict \fImqstat\fP, + struct mq_attr *restrict \fIomqstat\fP); +.fi +.SH DESCRIPTION +The +\fImq_setattr\fR() +function shall set attributes associated with the open message queue +description referenced by the message queue descriptor specified by +.IR mqdes . +.P +The message queue attributes corresponding to the following members +defined in the +.BR mq_attr +structure shall be set to the specified values upon successful +completion of +\fImq_setattr\fR(): +.IP "\fImq_flags\fP" 12 +The value of this member is the bitwise-logical OR of zero or more of +O_NONBLOCK and any implementation-defined flags. +.P +The values of the +.IR mq_maxmsg , +.IR mq_msgsize , +and +.IR mq_curmsgs +members of the +.BR mq_attr +structure shall be ignored by +\fImq_setattr\fR(). +.P +If +.IR omqstat +is non-NULL, the +\fImq_setattr\fR() +function shall store, in the location referenced by +.IR omqstat , +the previous message queue attributes and the current queue status. +These values shall be the same as would be returned by a call to +\fImq_getattr\fR() +at that point. +.SH "RETURN VALUE" +Upon successful completion, the function shall return a value of zero +and the attributes of the message queue shall have been changed as +specified. +.P +Otherwise, the message queue attributes shall be unchanged, and the +function shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_setattr\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR mqdes +argument is not a valid message queue descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_timedreceive.3p b/upstream/archlinux/man3p/mq_timedreceive.3p new file mode 100644 index 00000000..f0d7c9d9 --- /dev/null +++ b/upstream/archlinux/man3p/mq_timedreceive.3p @@ -0,0 +1,44 @@ +'\" et +.TH MQ_TIMEDRECEIVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_timedreceive +\(em receive a message from a message queue +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +ssize_t mq_timedreceive(mqd_t \fImqdes\fP, char *restrict \fImsg_ptr\fP, + size_t \fImsg_len\fP, unsigned *restrict \fImsg_prio\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImq_receive\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_timedsend.3p b/upstream/archlinux/man3p/mq_timedsend.3p new file mode 100644 index 00000000..7d80506d --- /dev/null +++ b/upstream/archlinux/man3p/mq_timedsend.3p @@ -0,0 +1,43 @@ +'\" et +.TH MQ_TIMEDSEND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_timedsend +\(em send a message to a message queue +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int mq_timedsend(mqd_t \fImqdes\fP, const char *\fImsg_ptr\fP, size_t \fImsg_len\fP, + unsigned \fImsg_prio\fP, const struct timespec *\fIabstime\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImq_send\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mq_unlink.3p b/upstream/archlinux/man3p/mq_unlink.3p new file mode 100644 index 00000000..aafe3db2 --- /dev/null +++ b/upstream/archlinux/man3p/mq_unlink.3p @@ -0,0 +1,135 @@ +'\" et +.TH MQ_UNLINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mq_unlink +\(em remove a message queue +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int mq_unlink(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fImq_unlink\fR() +function shall remove the message queue named by the string name. +If one or more processes have the message queue open when +\fImq_unlink\fR() +is called, destruction of the message queue shall be postponed until +all references to the message queue have been closed. However, the +\fImq_unlink\fR() +call need not block until all references have been closed; it may return +immediately. +.P +After a successful call to +\fImq_unlink\fR(), +reuse of the name shall subsequently cause +\fImq_open\fR() +to behave as if no message queue of this name exists (that is, +\fImq_open\fR() +will fail if O_CREAT is not set, or will create a new message queue if +O_CREAT is set). +.SH "RETURN VALUE" +Upon successful completion, the function shall return a value of zero. +Otherwise, the named message queue shall be unchanged by this function +call, and the function shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImq_unlink\fR() +function shall fail if: +.TP +.BR EACCES +Permission is denied to unlink the named message queue. +.TP +.BR EINTR +The call to +\fImq_unlink\fR() +blocked waiting for all references to the named message queue to be +closed and a signal interrupted the call. +.TP +.BR ENOENT +The named message queue does not exist. +.P +The +\fImq_unlink\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +A call to +\fImq_unlink\fR() +with a +.IR name +argument that contains the same message queue name as was previously +used in a successful +\fImq_open\fR() +call shall not give an +.BR [ENAMETOOLONG] +error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fImq_open\fR() +and +\fImq_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/mrand48.3p b/upstream/archlinux/man3p/mrand48.3p new file mode 100644 index 00000000..f7867060 --- /dev/null +++ b/upstream/archlinux/man3p/mrand48.3p @@ -0,0 +1,40 @@ +'\" et +.TH MRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +mrand48 +\(em generate uniformly distributed pseudo-random signed long integers +.SH SYNOPSIS +.LP +.nf +#include +.P +long mrand48(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/msgctl.3p b/upstream/archlinux/man3p/msgctl.3p new file mode 100644 index 00000000..a3c58506 --- /dev/null +++ b/upstream/archlinux/man3p/msgctl.3p @@ -0,0 +1,190 @@ +'\" et +.TH MSGCTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +msgctl +\(em XSI message control operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int msgctl(int \fImsqid\fP, int \fIcmd\fP, struct msqid_ds *\fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fImsgctl\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgctl\fR() +function shall provide message control operations as specified by +.IR cmd . +The following values for +.IR cmd , +and the message control operations they specify, are: +.IP IPC_STAT 12 +Place the current value of each member of the +.BR msqid_ds +data structure associated with +.IR msqid +into the structure pointed to by +.IR buf . +The contents of this structure are defined in +.IR . +.IP IPC_SET 12 +Set the value of the following members of the +.BR msqid_ds +data structure associated with +.IR msqid +to the corresponding value found in the structure pointed to by +.IR buf : +.RS 12 +.sp +.RS 4 +.nf + +msg_perm.uid +msg_perm.gid +msg_perm.mode +msg_qbytes +.fi +.P +.RE +.P +Also, the +.IR msg_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +IPC_SET can only be executed by a process with appropriate privileges +or that has an effective user ID equal to the value of +.BR msg_perm.cuid +or +.BR msg_perm.uid +in the +.BR msqid_ds +data structure associated with +.IR msqid . +Only a process with appropriate privileges can raise the value of +.BR msg_qbytes . +.RE +.IP IPC_RMID 12 +Remove the message queue identifier specified by +.IR msqid +from the system and destroy the message queue and +.BR msqid_ds +data structure associated with it. IPC_RMD can only be executed by a +process with appropriate privileges or one that has an effective user +ID equal to the value of +.BR msg_perm.cuid +or +.BR msg_perm.uid +in the +.BR msqid_ds +data structure associated with +.IR msqid . +.SH "RETURN VALUE" +Upon successful completion, +\fImsgctl\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImsgctl\fR() +function shall fail if: +.TP +.BR EACCES +The argument +.IR cmd +is IPC_STAT and the calling process does not have read permission; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR msqid +is not a valid message queue identifier; or the value of +.IR cmd +is not a valid command. +.TP +.BR EPERM +The argument +.IR cmd +is IPC_RMID or IPC_SET +and the effective user ID of the calling process is not equal to that +of a process with appropriate privileges and it is not equal to the +value of +.BR msg_perm.cuid +or +.BR msg_perm.uid +in the data structure associated with +.IR msqid . +.TP +.BR EPERM +The argument +.IR cmd +is IPC_SET, an attempt is being made to increase to the value of +.BR msg_qbytes , +and the effective user ID of the calling process does not have +appropriate privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/msgget.3p b/upstream/archlinux/man3p/msgget.3p new file mode 100644 index 00000000..813029fa --- /dev/null +++ b/upstream/archlinux/man3p/msgget.3p @@ -0,0 +1,166 @@ +'\" et +.TH MSGGET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +msgget +\(em get the XSI message queue identifier +.SH SYNOPSIS +.LP +.nf +#include +.P +int msgget(key_t \fIkey\fP, int \fImsgflg\fP); +.fi +.SH DESCRIPTION +The +\fImsgget\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgget\fR() +function shall return the message queue identifier associated with the +argument +.IR key . +.P +A message queue identifier, associated message queue, and data +structure (see +.IR ), +shall be created for the argument +.IR key +if one of the following is true: +.IP " *" 4 +The argument +.IR key +is equal to IPC_PRIVATE. +.IP " *" 4 +The argument +.IR key +does not already have a message queue identifier associated with it, +and (\fImsgflg\fP & IPC_CREAT) is non-zero. +.P +Upon creation, the data structure associated with the new message queue +identifier shall be initialized as follows: +.IP " *" 4 +.BR msg_perm.cuid , +.BR msg_perm.uid , +.BR msg_perm.cgid , +and +.BR msg_perm.gid +shall be set to the effective user ID and effective group ID, +respectively, of the calling process. +.IP " *" 4 +The low-order 9 bits of +.BR msg_perm.mode +shall be set to the low-order 9 bits of +.IR msgflg . +.IP " *" 4 +.BR msg_qnum , +.BR msg_lspid , +.BR msg_lrpid , +.BR msg_stime , +and +.BR msg_rtime +shall be set to 0. +.IP " *" 4 +.BR msg_ctime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.IP " *" 4 +.BR msg_qbytes +shall be set to the system limit. +.SH "RETURN VALUE" +Upon successful completion, +\fImsgget\fR() +shall return a non-negative integer, namely a message queue identifier. +Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImsgget\fR() +function shall fail if: +.TP +.BR EACCES +A message queue identifier exists for the argument +.IR key , +but operation permission as specified by the low-order 9 bits of +.IR msgflg +would not be granted; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EEXIST +A message queue identifier exists for the argument +.IR key +but ((\fImsgflg\fP & IPC_CREAT) && (\fImsgflg\fP & IPC_EXCL)) is +non-zero. +.TP +.BR ENOENT +A message queue identifier does not exist for the argument +.IR key +and (\fImsgflg\fP & IPC_CREAT) is 0. +.TP +.BR ENOSPC +A message queue identifier is to be created but the system-imposed +limit on the maximum number of allowed message queue identifiers +system-wide would be exceeded. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIftok\fR\^(\|)", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/msgrcv.3p b/upstream/archlinux/man3p/msgrcv.3p new file mode 100644 index 00000000..91f9c3fb --- /dev/null +++ b/upstream/archlinux/man3p/msgrcv.3p @@ -0,0 +1,274 @@ +'\" et +.TH MSGRCV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +msgrcv +\(em XSI message receive operation +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t msgrcv(int \fImsqid\fP, void *\fImsgp\fP, size_t \fImsgsz\fP, long \fImsgtyp\fP, + int \fImsgflg\fP); +.fi +.SH DESCRIPTION +The +\fImsgrcv\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgrcv\fR() +function shall read a message from the queue associated with the message +queue identifier specified by +.IR msqid +and place it in the user-defined buffer pointed to by +.IR msgp . +.P +The application shall ensure that the argument +.IR msgp +points to a user-defined buffer that contains first a field of type +.BR long +specifying the type of the message, and then a data portion that holds +the data bytes of the message. The structure below is an example of +what this user-defined buffer might look like: +.sp +.RS 4 +.nf + +struct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +.fi +.P +.RE +.P +The structure member +.IR mtype +is the received message's type as specified by the sending process. +.P +The structure member +.IR mtext +is the text of the message. +.P +The argument +.IR msgsz +specifies the size in bytes of +.IR mtext . +The received message shall be truncated to +.IR msgsz +bytes if it is larger than +.IR msgsz +and (\fImsgflg\fP & MSG_NOERROR) is non-zero. +The truncated part of the message shall be lost and no indication of +the truncation shall be given to the calling process. +.P +If the value of +.IR msgsz +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +The argument +.IR msgtyp +specifies the type of message requested as follows: +.IP " *" 4 +If +.IR msgtyp +is 0, the first message on the queue shall be received. +.IP " *" 4 +If +.IR msgtyp +is greater than 0, the first message of type +.IR msgtyp +shall be received. +.IP " *" 4 +If +.IR msgtyp +is less than 0, the first message of the lowest type that is less than +or equal to the absolute value of +.IR msgtyp +shall be received. +.P +The argument +.IR msgflg +specifies the action to be taken if a message of the desired type is +not on the queue. These are as follows: +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) +is non-zero, the calling thread shall return immediately with a return +value of \-1 and +.IR errno +set to +.BR [ENOMSG] . +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend +execution until one of the following occurs: +.RS 4 +.IP -- 4 +A message of the desired type is placed on the queue. +.IP -- 4 +The message queue identifier +.IR msqid +is removed from the system; when this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \-1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught; in this case +a message is not received and the calling thread resumes execution in +the manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.P +Upon successful completion, the following actions are taken with +respect to the data structure associated with +.IR msqid : +.IP " *" 4 +.BR msg_qnum +shall be decremented by 1. +.IP " *" 4 +.BR msg_lrpid +shall be set to the process ID of the calling process. +.IP " *" 4 +.BR msg_rtime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.SH "RETURN VALUE" +Upon successful completion, +\fImsgrcv\fR() +shall return a value equal to the number of bytes actually placed +into the buffer +.IR mtext . +Otherwise, no message shall be received, +\fImsgrcv\fR() +shall return \-1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fImsgrcv\fR() +function shall fail if: +.TP +.BR E2BIG +The value of +.IR mtext +is greater than +.IR msgsz +and (\fImsgflg\fP & MSG_NOERROR) is 0. +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EIDRM +The message queue identifier +.IR msqid +is removed from the system. +.TP +.BR EINTR +The +\fImsgrcv\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +.IR msqid +is not a valid message queue identifier. +.TP +.BR ENOMSG +The queue does not contain a message of the desired type and +(\fImsgflg\fP & IPC_NOWAIT) is non-zero. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Receiving a Message" +.P +The following example receives the first message on the queue (based on +the value of the +.IR msgtyp +argument, 0). The queue is identified by the +.IR msqid +argument (assuming that the value has previously been set). This call +specifies that an error should be reported if no message is available, +but not if the message is too large. The message size is calculated +directly using the +.IR sizeof +operator. +.sp +.RS 4 +.nf + +#include +\&... +int result; +int msqid; +struct message { + long type; + char text[20]; +} msg; +long msgtyp = 0; +\&... +result = msgrcv(msqid, (void *) &msg, sizeof(msg.text), + msgtyp, MSG_NOERROR | IPC_NOWAIT); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgsnd\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/msgsnd.3p b/upstream/archlinux/man3p/msgsnd.3p new file mode 100644 index 00000000..ce36203e --- /dev/null +++ b/upstream/archlinux/man3p/msgsnd.3p @@ -0,0 +1,241 @@ +'\" et +.TH MSGSND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +msgsnd +\(em XSI message send operation +.SH SYNOPSIS +.LP +.nf +#include +.P +int msgsnd(int \fImsqid\fP, const void *\fImsgp\fP, size_t \fImsgsz\fP, int \fImsgflg\fP); +.fi +.SH DESCRIPTION +The +\fImsgsnd\fR() +function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fImsgsnd\fR() +function shall send a message to the queue associated with the +message queue identifier specified by +.IR msqid . +.P +The application shall ensure that the argument +.IR msgp +points to a user-defined buffer that contains first a field of type +.BR long +specifying the type of the message, and then a data portion that holds +the data bytes of the message. The structure below is an example of +what this user-defined buffer might look like: +.sp +.RS 4 +.nf + +struct mymsg { + long mtype; /* Message type. */ + char mtext[1]; /* Message text. */ +} +.fi +.P +.RE +.P +The structure member +.IR mtype +is a non-zero positive type +.BR long +that can be used by the receiving process for message selection. +.P +The structure member +.IR mtext +is any text of length +.IR msgsz +bytes. The argument +.IR msgsz +can range from 0 to a system-imposed maximum. +.P +The argument +.IR msgflg +specifies the action to be taken if one or more of the following is +true: +.IP " *" 4 +The number of bytes already on the queue is equal to +.BR msg_qbytes ; +see +.IR . +.IP " *" 4 +The total number of messages on all queues system-wide is equal to the +system-imposed limit. +.P +These actions are as follows: +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) +is non-zero, the message shall not be sent and the calling thread +shall return immediately. +.IP " *" 4 +If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend +execution until one of the following occurs: +.RS 4 +.IP -- 4 +The condition responsible for the suspension no longer exists, in which +case the message is sent. +.IP -- 4 +The message queue identifier +.IR msqid +is removed from the system; when this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \-1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught; in this case +the message is not sent and the calling thread resumes execution in the +manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.br +.P +Upon successful completion, the following actions are taken with +respect to the data structure associated with +.IR msqid ; +see +.IR : +.IP " *" 4 +.BR msg_qnum +shall be incremented by 1. +.IP " *" 4 +.BR msg_lspid +shall be set to the process ID of the calling process. +.IP " *" 4 +.BR msg_stime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.SH "RETURN VALUE" +Upon successful completion, +\fImsgsnd\fR() +shall return 0; otherwise, no message shall be sent, +\fImsgsnd\fR() +shall return \-1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fImsgsnd\fR() +function shall fail if: +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EAGAIN +The message cannot be sent for one of the reasons cited above and +(\fImsgflg\fP & IPC_NOWAIT) is non-zero. +.TP +.BR EIDRM +The message queue identifier +.IR msqid +is removed from the system. +.TP +.BR EINTR +The +\fImsgsnd\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The value of +.IR msqid +is not a valid message queue identifier, or the value of +.IR mtype +is less than 1; or the value of +.IR msgsz +is greater than the system-imposed limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending a Message" +.P +The following example sends a message to the queue identified by the +.IR msqid +argument (assuming that value has previously been set). This call +specifies that an error should be reported if no message is available. +The message size is calculated directly using the +.IR sizeof +operator. +.sp +.RS 4 +.nf + +#include +\&... +int result; +int msqid; +struct message { + long type; + char text[20]; +} msg; +.P +msg.type = 1; +strcpy(msg.text, "This is message 1"); +\&... +result = msgsnd(msqid, (void *) &msg, sizeof(msg.text), IPC_NOWAIT); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess communication +(IPC). Application developers who need to use IPC should design their +applications so that modules using the IPC routines described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fImq_close\fR\^(\|)", +.IR "\fImq_getattr\fR\^(\|)", +.IR "\fImq_notify\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fImq_setattr\fR\^(\|)", +.IR "\fImq_unlink\fR\^(\|)", +.IR "\fImsgctl\fR\^(\|)", +.IR "\fImsgget\fR\^(\|)", +.IR "\fImsgrcv\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.226" ", " "Message Queue", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/msync.3p b/upstream/archlinux/man3p/msync.3p new file mode 100644 index 00000000..ba461b6b --- /dev/null +++ b/upstream/archlinux/man3p/msync.3p @@ -0,0 +1,193 @@ +'\" et +.TH MSYNC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +msync +\(em synchronize memory with physical storage +.SH SYNOPSIS +.LP +.nf +#include +.P +int msync(void *\fIaddr\fP, size_t \fIlen\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fImsync\fR() +function shall write all modified data to permanent storage locations, +if any, in those whole pages containing any part of the address space of +the process starting at address +.IR addr +and continuing for +.IR len +bytes. If no such storage exists, +\fImsync\fR() +need not have any effect. If requested, the +\fImsync\fR() +function shall then invalidate cached copies of data. +.P +The implementation may require that +.IR addr +be a multiple of the page size as returned by +\fIsysconf\fR(). +.P +For mappings to files, the +\fImsync\fR() +function shall ensure that all write operations are completed as +defined for synchronized I/O data integrity completion. It is +unspecified whether the implementation also writes out other file +attributes. When the +\fImsync\fR() +function is called on MAP_PRIVATE mappings, any modified data shall +not be written to the underlying object and shall not cause such data +to be made visible to other processes. It is unspecified whether data +in MAP_PRIVATE mappings has any permanent storage locations. +The effect of +\fImsync\fR() +on a shared memory object or a typed memory object is unspecified. +The behavior of this function is unspecified if the mapping was not +established by a call to +\fImmap\fR(). +.P +The +.IR flags +argument is constructed from the bitwise-inclusive OR of one or more of +the following flags defined in the +.IR +header: +.TS +center box tab(!); +cB | cB +lw(1.5i) | lw(2i). +Symbolic Constant!Description +_ +MS_ASYNC!Perform asynchronous writes. +MS_SYNC!Perform synchronous writes. +MS_INVALIDATE!Invalidate cached data. +.TE +.P +When MS_ASYNC is specified, +\fImsync\fR() +shall return immediately once all the write operations are initiated or +queued for servicing; when MS_SYNC is specified, +\fImsync\fR() +shall not return until all write operations are completed as defined for +synchronized I/O data integrity completion. Either MS_ASYNC or MS_SYNC +shall be specified, but not both. +.P +When MS_INVALIDATE is specified, +\fImsync\fR() +shall invalidate all cached copies of mapped data that are inconsistent +with the permanent storage locations such that subsequent references +shall obtain data that was consistent with the permanent storage +locations sometime between the call to +\fImsync\fR() +and the first subsequent memory reference to the data. +.P +If +\fImsync\fR() +causes any write to a file, the file's last data modification and +last file status change timestamps shall be marked for update. +.SH "RETURN VALUE" +Upon successful completion, +\fImsync\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImsync\fR() +function shall fail if: +.TP +.BR EBUSY +Some or all of the addresses in the range starting at +.IR addr +and continuing for +.IR len +bytes are locked, and MS_INVALIDATE is specified. +.TP +.BR EINVAL +The value of +.IR flags +is invalid. +.TP +.BR ENOMEM +The addresses in the range starting at +.IR addr +and continuing for +.IR len +bytes are outside the range allowed for the address space of a process +or specify one or more pages that are not mapped. +.P +The +\fImsync\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR addr +is not a multiple of the page size as returned by +\fIsysconf\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fImsync\fR() +function is only supported if the Synchronized Input and Output +option is supported, and thus need not be available on all implementations. +.P +The +\fImsync\fR() +function should be used by programs that require a memory object to be +in a known state; for example, in building transaction facilities. +.P +Normal system activity can cause pages to be written to disk. +Therefore, there are no guarantees that +\fImsync\fR() +is the only control over when pages are or are not written to disk. +.SH RATIONALE +The +\fImsync\fR() +function writes out data in a mapped region to the permanent +storage for the underlying object. The call to +\fImsync\fR() +ensures data integrity of the file. +.P +After the data is written out, any cached data may be invalidated if +the MS_INVALIDATE +flag was specified. This is useful on systems that do not support +read/write consistency. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/munlock.3p b/upstream/archlinux/man3p/munlock.3p new file mode 100644 index 00000000..7f5af6ec --- /dev/null +++ b/upstream/archlinux/man3p/munlock.3p @@ -0,0 +1,40 @@ +'\" et +.TH MUNLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +munlock +\(em unlock a range of process address space +.SH SYNOPSIS +.LP +.nf +#include +.P +int munlock(const void *\fIaddr\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImlock\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/munlockall.3p b/upstream/archlinux/man3p/munlockall.3p new file mode 100644 index 00000000..43908fac --- /dev/null +++ b/upstream/archlinux/man3p/munlockall.3p @@ -0,0 +1,40 @@ +'\" et +.TH MUNLOCKALL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +munlockall +\(em unlock the address space of a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int munlockall(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fImlockall\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/munmap.3p b/upstream/archlinux/man3p/munmap.3p new file mode 100644 index 00000000..89d1693b --- /dev/null +++ b/upstream/archlinux/man3p/munmap.3p @@ -0,0 +1,145 @@ +'\" et +.TH MUNMAP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +munmap +\(em unmap pages of memory +.SH SYNOPSIS +.LP +.nf +#include +.P +int munmap(void *\fIaddr\fP, size_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fImunmap\fR() +function shall remove any mappings for those entire pages containing +any part of the address space of the process starting at +.IR addr +and continuing for +.IR len +bytes. Further references to these pages shall result in the +generation of a SIGSEGV signal to the process. +If there are no mappings in the specified address range, then +\fImunmap\fR() +has no effect. +.P +The implementation may require that +.IR addr +be a multiple of the page size as returned by +\fIsysconf\fR(). +.P +If a mapping to be removed was private, any modifications made in this +address range shall be discarded. +.P +Any memory locks (see +.IR "\fImlock\fR\^(\|)" +and +.IR "\fImlockall\fR\^(\|)") +associated with this address range shall be removed, as if by an +appropriate call to +\fImunlock\fR(). +.P +If a mapping removed from a typed memory object causes the +corresponding address range of the memory pool to be inaccessible by +any process in the system except through allocatable mappings (that is, +mappings of typed memory objects opened with the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag), then that range of the memory +pool shall become deallocated and may become available to satisfy +future typed memory allocation requests. +.P +A mapping removed from a typed memory object opened with the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag shall not affect in any way the +availability of that typed memory for allocation. +.P +The behavior of this function is unspecified if the mapping was not +established by a call to +\fImmap\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fImunmap\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fImunmap\fR() +function shall fail if: +.TP +.BR EINVAL +Addresses in the range [\fIaddr\fP,\fIaddr\fP+\fIlen\fR) are outside +the valid range for the address space of a process. +.TP +.BR EINVAL +The +.IR len +argument is 0. +.P +The +\fImunmap\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR addr +argument is not a multiple of the page size as returned by +\fIsysconf\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fImunmap\fR() +function corresponds to SVR4, just as the +\fImmap\fR() +function does. +.P +It is possible that an application has applied process memory locking +to a region that contains shared memory. If this has occurred, the +\fImunmap\fR() +call ignores those locks and, if necessary, causes those locks to be +removed. +.P +Most implementations require that +.IR addr +is a multiple of the page size as returned by +\fIsysconf\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImlock\fR\^(\|)", +.IR "\fImlockall\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nan.3p b/upstream/archlinux/man3p/nan.3p new file mode 100644 index 00000000..60dd1ad6 --- /dev/null +++ b/upstream/archlinux/man3p/nan.3p @@ -0,0 +1,114 @@ +'\" et +.TH NAN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nan, +nanf, +nanl +\(em return quiet NaN +.SH SYNOPSIS +.LP +.nf +#include +.P +double nan(const char *\fItagp\fP); +float nanf(const char *\fItagp\fP); +long double nanl(const char *\fItagp\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The function call \fInan\fR("\fIn-char-sequence\fR") shall be +equivalent to: +.sp +.RS 4 +.nf + +strtod("NAN(\fIn-char-sequence\fP)", (char **) NULL); +.fi +.P +.RE +.P +The function call \fInan\fR("\|") shall be equivalent to: +.sp +.RS 4 +.nf + +strtod("NAN()", (char **) NULL) +.fi +.P +.RE +.P +If +.IR tagp +does not point to an +.IR n -\c +.BR char +sequence or an empty string, the function call shall be equivalent to: +.sp +.RS 4 +.nf + +strtod("NAN", (char **) NULL) +.fi +.P +.RE +.P +Function calls to +\fInanf\fR() +and +\fInanl\fR() +are equivalent to the corresponding function calls to +\fIstrtof\fR() +and +\fIstrtold\fR(). +.SH "RETURN VALUE" +These functions shall return a quiet NaN, if available, with content +indicated through +.IR tagp . +.P +If the implementation does not support quiet NaNs, these functions +shall return zero. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nanosleep.3p b/upstream/archlinux/man3p/nanosleep.3p new file mode 100644 index 00000000..25e45809 --- /dev/null +++ b/upstream/archlinux/man3p/nanosleep.3p @@ -0,0 +1,147 @@ +'\" et +.TH NANOSLEEP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nanosleep +\(em high resolution sleep +.SH SYNOPSIS +.LP +.nf +#include +.P +int nanosleep(const struct timespec *\fIrqtp\fP, struct timespec *\fIrmtp\fP); +.fi +.SH DESCRIPTION +The +\fInanosleep\fR() +function shall cause the current thread to be suspended from execution +until either the time interval specified by the +.IR rqtp +argument has elapsed or a signal is delivered to the calling thread, +and its action is to invoke a signal-catching function or to terminate +the process. The suspension time may be longer than requested because +the argument value is rounded up to an integer multiple of the sleep +resolution or because of the scheduling of other activity by the +system. But, except for the case of being interrupted by a signal, the +suspension time shall not be less than the time specified by +.IR rqtp , +as measured by the system clock CLOCK_REALTIME. +.P +The use of the +\fInanosleep\fR() +function has no effect on the action or blockage of any signal. +.SH "RETURN VALUE" +If the +\fInanosleep\fR() +function returns because the requested time has elapsed, its return +value shall be zero. +.P +If the +\fInanosleep\fR() +function returns because it has been interrupted by a signal, it +shall return a value of \-1 and set +.IR errno +to indicate the interruption. If the +.IR rmtp +argument is non-NULL, the +.BR timespec +structure referenced by it is updated to contain the amount of time +remaining in the interval (the requested time minus the time actually +slept). The +.IR rqtp +and +.IR rmtp +arguments can point to the same object. If the +.IR rmtp +argument is NULL, the remaining time is not returned. +.P +If +\fInanosleep\fR() +fails, it shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fInanosleep\fR() +function shall fail if: +.TP +.BR EINTR +The +\fInanosleep\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The +.IR rqtp +argument specified a nanosecond value less than zero or greater than or +equal to 1\|000 million. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +It is common to suspend execution of a thread for an interval in order +to poll the status of a non-interrupting function. A large number of +actual needs can be met with a simple extension to +\fIsleep\fR() +that provides finer resolution. +.P +In the POSIX.1\(hy1990 standard and SVR4, it is possible to implement such a routine, +but the frequency of wakeup is limited by the resolution of the +\fIalarm\fR() +and +\fIsleep\fR() +functions. In 4.3 BSD, it is possible to write such a routine using +no static storage and reserving no system facilities. Although it is +possible to write a function with similar functionality to +\fIsleep\fR() +using the remainder of the +.IR timer_* (\|) +functions, such a function requires the use of signals and the +reservation of some signal number. This volume of POSIX.1\(hy2017 requires that +\fInanosleep\fR() +be non-intrusive of the signals function. +.P +The +\fInanosleep\fR() +function shall return a value of 0 on success and \-1 on failure or if +interrupted. This latter case is different from +\fIsleep\fR(). +This was done because the remaining time is returned via an argument +structure pointer, +.IR rmtp , +instead of as the return value. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_nanosleep\fR\^(\|)", +.IR "\fIsleep\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nearbyint.3p b/upstream/archlinux/man3p/nearbyint.3p new file mode 100644 index 00000000..991be3d5 --- /dev/null +++ b/upstream/archlinux/man3p/nearbyint.3p @@ -0,0 +1,91 @@ +'\" et +.TH NEARBYINT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nearbyint, +nearbyintf, +nearbyintl +\(em floating-point rounding functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double nearbyint(double \fIx\fP); +float nearbyintf(float \fIx\fP); +long double nearbyintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall round their argument to an integer value in +floating-point format, using the current rounding direction and without +raising the inexact floating-point exception. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, \(+-0 shall be returned. +.P +If +.IR x +is \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/newlocale.3p b/upstream/archlinux/man3p/newlocale.3p new file mode 100644 index 00000000..22fb47e2 --- /dev/null +++ b/upstream/archlinux/man3p/newlocale.3p @@ -0,0 +1,267 @@ +'\" et +.TH NEWLOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +newlocale +\(em create or modify a locale object +.SH SYNOPSIS +.LP +.nf +#include +.P +locale_t newlocale(int \fIcategory_mask\fP, const char *\fIlocale\fP, + locale_t \fIbase\fP); +.fi +.SH DESCRIPTION +The +\fInewlocale\fR() +function shall create a new locale object or modify an existing one. +If the +.IR base +argument is (\c +.BR locale_t )0, +a new locale object shall be created. It is unspecified whether the +locale object pointed to by +.IR base +shall be modified, or freed and a new locale object created. +.P +The +.IR category_mask +argument specifies the locale categories to be set or modified. +Values for +.IR category_mask +shall be constructed by a bitwise-inclusive OR of the symbolic +constants +.IR LC_CTYPE_MASK , +.IR LC_NUMERIC_MASK , +.IR LC_TIME_MASK , +.IR LC_COLLATE_MASK , +.IR LC_MONETARY_MASK , +and +.IR LC_MESSAGES_MASK , +or any of the implementation-defined mask values defined in +.IR . +.P +For each category with the corresponding bit set in +.IR category_mask +the data from the locale named by +.IR locale +shall be used. In the case of modifying an existing locale object, the +data from the locale named by +.IR locale +shall replace the existing data within the locale object. If a completely +new locale object is created, the data for all sections not requested by +.IR category_mask +shall be taken from the default locale. +.P +The following preset values of +.IR locale +are defined for all settings of +.IR category_mask : +.IP "\&\(dqPOSIX\(dq" 12 +Specifies the minimal environment for C-language translation called +the POSIX locale. +.IP "\&\(dqC\(dq" 12 +Equivalent to +.BR \(dqPOSIX\(dq . +.IP "\&\(dq\|\(dq" 12 +Specifies an implementation-defined native environment. This corresponds +to the value of the associated environment variables, +.IR LC_* +and +.IR LANG ; +see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale" +and +.IR "Chapter 8" ", " "Environment Variables". +.P +If the +.IR base +argument is not (\c +.BR locale_t )0 +and the +\fInewlocale\fR() +function call succeeds, the contents of +.IR base +are unspecified. Applications shall ensure that they stop using +.IR base +as a locale object before calling +\fInewlocale\fR(). +If the function call fails and the +.IR base +argument is not (\c +.BR locale_t )0, +the contents of +.IR base +shall remain valid and unchanged. +.P +The behavior is undefined if the +.IR base +argument is the special locale object LC_GLOBAL_LOCALE, or is not a +valid locale object handle and is not (\c +.BR locale_t )0. +.SH "RETURN VALUE" +Upon successful completion, the +\fInewlocale\fR() +function shall return a handle which the caller may use on subsequent +calls to +\fIduplocale\fR(), +\fIfreelocale\fR(), +and other functions taking a +.BR locale_t +argument. +.P +Upon failure, the +\fInewlocale\fR() +function shall return (\c +.BR locale_t )0 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fInewlocale\fR() +function shall fail if: +.TP +.BR ENOMEM +There is not enough memory available to create the locale object or +load the locale data. +.TP +.BR EINVAL +The +.IR category_mask +contains a bit that does not correspond to a valid category. +.TP +.BR ENOENT +For any of the categories in +.IR category_mask , +the locale data is not available. +.P +The +\fInewlocale\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR locale +argument is not a valid string pointer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Constructing a Locale Object from Different Locales" +.P +The following example shows the construction of a locale where the +.IR LC_CTYPE +category data comes from a locale +.IR loc1 +and the +.IR LC_TIME +category data from a locale +.IR loc2 : +.sp +.RS 4 +.nf + +#include +\&... +locale_t loc, new_loc; +.P +/* Get the "loc1" data. */ +.P +loc = newlocale (LC_CTYPE_MASK, "loc1", (locale_t)0); +if (loc == (locale_t) 0) + abort (); +.P +/* Get the "loc2" data. */ +.P +new_loc = newlocale (LC_TIME_MASK, "loc2", loc); +if (new_loc != (locale_t) 0) + /* We don t abort if this fails. In this case this + simply used to unchanged locale object. */ + loc = new_loc; +.P +\&... +.fi +.P +.RE +.SS "Freeing up a Locale Object" +.P +The following example shows a code fragment to free a locale object +created by +\fInewlocale\fR(): +.sp +.RS 4 +.nf + +#include +\&... +.P +/* Every locale object allocated with newlocale() should be + * freed using freelocale(): + */ +.P +locale_t loc; +.P +/* Get the locale. */ +.P +loc = newlocale (LC_CTYPE_MASK | LC_TIME_MASK, "locname", (locale_t)0); +.P +/* ... Use the locale object ... */ +\&... +.P +/* Free the locale object resources. */ +freelocale (loc); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Handles for locale objects created by the +\fInewlocale\fR() +function should either be released by a corresponding call to +\fIfreelocale\fR(), +or be used as a base locale to another +\fInewlocale\fR() +call. +.P +The special locale object LC_GLOBAL_LOCALE must not be passed for the +.IR base +argument, even when returned by the +\fIuselocale\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIduplocale\fR\^(\|)", +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nextafter.3p b/upstream/archlinux/man3p/nextafter.3p new file mode 100644 index 00000000..e7ae2405 --- /dev/null +++ b/upstream/archlinux/man3p/nextafter.3p @@ -0,0 +1,198 @@ +'\" et +.TH NEXTAFTER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nextafter, +nextafterf, +nextafterl, +nexttoward, +nexttowardf, +nexttowardl +\(em next representable floating-point number +.SH SYNOPSIS +.LP +.nf +#include +.P +double nextafter(double \fIx\fP, double \fIy\fP); +float nextafterf(float \fIx\fP, float \fIy\fP); +long double nextafterl(long double \fIx\fP, long double \fIy\fP); +double nexttoward(double \fIx\fP, long double \fIy\fP); +float nexttowardf(float \fIx\fP, long double \fIy\fP); +long double nexttowardl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fInextafter\fR(), +\fInextafterf\fR(), +and +\fInextafterl\fR() +functions shall compute the next representable floating-point value +following +.IR x +in the direction of +.IR y . +Thus, if +.IR y +is less than +.IR x , +\fInextafter\fR() +shall return the largest representable floating-point number less than +.IR x . +The +\fInextafter\fR(), +\fInextafterf\fR(), +and +\fInextafterl\fR() +functions shall return +.IR y +if +.IR x +equals +.IR y . +.P +The +\fInexttoward\fR(), +\fInexttowardf\fR(), +and +\fInexttowardl\fR() +functions shall be equivalent to the corresponding +\fInextafter\fR() +functions, except that the second parameter shall have type +.BR "long double" +and the functions shall return +.IR y +converted to the type of the function if +.IR x +equals +.IR y . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the next +representable floating-point value following +.IR x +in the direction of +.IR y . +.P +If +.IR x ==\c +.IR y , +.IR y +(of the type +.IR x ) +shall be returned. +.P +If +.IR x +is finite and the correct function value would overflow, a range error +shall occur and \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (with +the same sign as +.IR x ) +shall be returned as appropriate for the return type of the function. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If +.IR x !=\c +.IR y +and the correct function value is subnormal, zero, or underflows, +a range error shall occur, and +.br +the correct function value (if representable) or +.br +0.0 shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The correct value overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The correct value is subnormal or underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.P +When +.IR +is included, note that the return type of +\fInextafter\fR() +depends on the generic typing deduced from both arguments, while the +return type of +\fInexttoward\fR() +depends only on the generic typing of the first argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nftw.3p b/upstream/archlinux/man3p/nftw.3p new file mode 100644 index 00000000..baf46d20 --- /dev/null +++ b/upstream/archlinux/man3p/nftw.3p @@ -0,0 +1,360 @@ +'\" et +.TH NFTW "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nftw +\(em walk a file tree +.SH SYNOPSIS +.LP +.nf +#include +.P +int nftw(const char *\fIpath\fP, int (*\fIfn\fP)(const char *, + const struct stat *, int, struct FTW *), int \fIfd_limit\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fInftw\fR() +function shall recursively descend the directory hierarchy rooted in +.IR path . +The +\fInftw\fR() +function has a similar effect to +\fIftw\fR() +except that it takes an additional argument +.IR flags , +which is a bitwise-inclusive OR of zero or more of the following flags: +.IP FTW_CHDIR 12 +If set, +\fInftw\fR() +shall change the current working directory to each directory as it +reports files in that directory. If clear, +\fInftw\fR() +shall not change the current working directory. +.IP FTW_DEPTH 12 +If set, +\fInftw\fR() +shall report all files in a directory before reporting the directory +itself. If clear, +\fInftw\fR() +shall report any directory before reporting the files in that directory. +.IP FTW_MOUNT 12 +If set, +\fInftw\fR() +shall only report files in the same file system as +.IR path . +If clear, +\fInftw\fR() +shall report all files encountered during the walk. +.IP FTW_PHYS 12 +If set, +\fInftw\fR() +shall perform a physical walk and shall not follow symbolic links. +.P +If FTW_PHYS is clear and FTW_DEPTH is set, +\fInftw\fR() +shall follow links instead of reporting them, but shall not report any +directory that would be a descendant of itself. If FTW_PHYS is clear +and FTW_DEPTH is clear, +\fInftw\fR() +shall follow links instead of reporting them, but shall not report the +contents of any directory that would be a descendant of itself. +.P +At each file it encounters, +\fInftw\fR() +shall call the user-supplied function +.IR fn +with four arguments: +.IP " *" 4 +The first argument is the pathname of the object. +.IP " *" 4 +The second argument is a pointer to the +.BR stat +buffer containing information on the object, filled in as if +\fIfstatat\fR(), +\fIstat\fR(), +or +\fIlstat\fR() +had been called to retrieve the information. +.IP " *" 4 +The third argument is an integer giving additional information. Its +value is one of the following: +.RS 4 +.IP FTW_D 10 +The object is a directory. +.IP FTW_DNR 10 +The object is a directory that cannot be read. The +.IR fn +function shall not be called for any of its descendants. +.IP FTW_DP 10 +The object is a directory and subdirectories have been visited. (This +condition shall only occur if the FTW_DEPTH flag is included in +.IR flags .) +.IP FTW_F 10 +The object is a non-directory file. +.IP FTW_NS 10 +The +\fIstat\fR() +function failed on the object because of lack of appropriate +permission. The +.BR stat +buffer passed to +.IR fn +is undefined. Failure of +\fIstat\fR() +for any other reason is considered an error and +\fInftw\fR() +shall return \-1. +.IP FTW_SL 10 +The object is a symbolic link. (This condition shall only occur if the +FTW_PHYS flag is included in +.IR flags .) +.IP FTW_SLN 10 +The object is a symbolic link that does not name an existing file. +(This condition shall only occur if the FTW_PHYS flag is not included in +.IR flags .) +.RE +.IP " *" 4 +The fourth argument is a pointer to an +.BR FTW +structure. +The value of +.BR base +is the offset of the object's filename in the pathname passed as the +first argument to +.IR fn . +The value of +.BR level +indicates depth relative to the root of the walk, where the root level +is 0. +.P +The results are unspecified if the application-supplied +.IR fn +function does not preserve the current working directory. +.P +The argument +.IR fd_limit +sets the maximum number of file descriptors that shall be used by +\fInftw\fR() +while traversing the file tree. At most one file descriptor shall be +used for each directory level. +.P +The +\fInftw\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +The +\fInftw\fR() +function shall continue until the first of the following conditions +occurs: +.IP " *" 4 +An invocation of +.IR fn +shall return a non-zero value, in which case +\fInftw\fR() +shall return that value. +.IP " *" 4 +The +\fInftw\fR() +function detects an error other than +.BR [EACCES] +(see FTW_DNR and FTW_NS above), +in which case +\fInftw\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.IP " *" 4 +The tree is exhausted, in which case +\fInftw\fR() +shall return 0. +.SH ERRORS +The +\fInftw\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied for any component of +.IR path +or read permission is denied for +.IR path , +or +.IR fn +returns \-1 and does not reset +.IR errno . +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of +.IR path +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EOVERFLOW +A field in the +.BR stat +structure cannot be represented correctly in the current programming +environment for one or more files found in the file hierarchy. +.P +The +\fInftw\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENFILE +Too many files are currently open in the system. +.P +In addition, +.IR errno +may be set if the function pointed to by +.IR fn +causes +.IR errno +to be set. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following program traverses the directory tree under the path named +in its first command-line argument, or under the current directory if +no argument is supplied. It displays various information about each +file. The second command-line argument can be used to specify characters +that control the value assigned to the +.IR flags +argument when calling +\fInftw\fR(). +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +.P +static int +display_info(const char *fpath, const struct stat *sb, + int tflag, struct FTW *ftwbuf) +{ + printf("%-3s %2d %7jd %-40s %d %s\en", + (tflag == FTW_D) ? "d" : (tflag == FTW_DNR) ? "dnr" : + (tflag == FTW_DP) ? "dp" : (tflag == FTW_F) ? + (S_ISBLK(sb->st_mode) ? "f b" : + S_ISCHR(sb->st_mode) ? "f c" : + S_ISFIFO(sb->st_mode) ? "f p" : + S_ISREG(sb->st_mode) ? "f r" : + S_ISSOCK(sb->st_mode) ? "f s" : "f ?") : + (tflag == FTW_NS) ? "ns" : (tflag == FTW_SL) ? "sl" : + (tflag == FTW_SLN) ? "sln" : "?", + ftwbuf->level, (intmax_t) sb->st_size, + fpath, ftwbuf->base, fpath + ftwbuf->base); + return 0; /* To tell nftw() to continue */ +} +.P +int +main(int argc, char *argv[]) +{ + int flags = 0; +.P + if (argc > 2 && strchr(argv[2], \(aqd\(aq) != NULL) + flags |= FTW_DEPTH; + if (argc > 2 && strchr(argv[2], \(aqp\(aq) != NULL) + flags |= FTW_PHYS; +.P + if (nftw((argc < 2) ? "." : argv[1], display_info, 20, flags) == -1) + { + perror("nftw"); + exit(EXIT_FAILURE); + } +.P + exit(EXIT_SUCCESS); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fInftw\fR() +function may allocate dynamic storage during its operation. If +\fInftw\fR() +is forcibly terminated, such as by +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +being executed by the function pointed to by +.IR fn +or an interrupt routine, +\fInftw\fR() +does not have a chance to free that storage, so it remains permanently +allocated. A safe way to handle interrupts is to store the fact that an +interrupt has occurred, and arrange to have the function pointed to by +.IR fn +return a non-zero value at its next invocation. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nice.3p b/upstream/archlinux/man3p/nice.3p new file mode 100644 index 00000000..d2d9ac7c --- /dev/null +++ b/upstream/archlinux/man3p/nice.3p @@ -0,0 +1,124 @@ +'\" et +.TH NICE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nice +\(em change the nice value of a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int nice(int \fIincr\fP); +.fi +.SH DESCRIPTION +The +\fInice\fR() +function shall add the value of +.IR incr +to the nice value of the calling process. A nice value of a process is +a non-negative number for which a more positive value shall result in +less favorable scheduling. +.P +A maximum nice value of 2*{NZERO}\-1 and a minimum nice value of 0 +shall be imposed by the system. Requests for values above or below +these limits shall result in the nice value being set to the +corresponding limit. Only a process with appropriate privileges can +lower the nice value. +.P +Calling the +\fInice\fR() +function has no effect on the priority of processes or threads with +policy SCHED_FIFO or SCHED_RR. +The effect on processes or threads with other scheduling policies is +implementation-defined. +.P +The nice value set with +\fInice\fR() +shall be applied to the process. If the process is multi-threaded, +the nice value shall affect all system scope threads in the process. +.P +As \-1 is a permissible return value in a successful situation, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fInice\fR(), +and if it returns \-1, check to see whether +.IR errno +is non-zero. +.SH "RETURN VALUE" +Upon successful completion, +\fInice\fR() +shall return the new nice value \-{NZERO}. +Otherwise, \-1 shall be returned, the nice value of the process +shall not be changed, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fInice\fR() +function shall fail if: +.TP +.BR EPERM +The +.IR incr +argument is negative and the calling process does not have appropriate +privileges. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Nice Value" +.P +The following example adds the value of the +.IR incr +argument, \-20, to the nice value of the calling process. +.sp +.RS 4 +.nf + +#include +\&... +int incr = -20; +int ret; +.P +ret = nice(incr); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetpriority\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nl_langinfo.3p b/upstream/archlinux/man3p/nl_langinfo.3p new file mode 100644 index 00000000..6d1cdeda --- /dev/null +++ b/upstream/archlinux/man3p/nl_langinfo.3p @@ -0,0 +1,209 @@ +'\" et +.TH NL_LANGINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nl_langinfo, +nl_langinfo_l +\(em language information +.SH SYNOPSIS +.LP +.nf +#include +.P +char *nl_langinfo(nl_item \fIitem\fP); +char *nl_langinfo_l(nl_item \fIitem\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +The +\fInl_langinfo\fR() +and +\fInl_langinfo_l\fR() +functions shall return a pointer to a string containing information +relevant to the particular language or cultural area defined in the +current locale, or in the locale represented by +.IR locale , +respectively (see +.IR ). +The manifest constant names and values of +.IR item +are defined in +.IR . +For example: +.sp +.RS 4 +.nf + +nl_langinfo(ABDAY_1) +.fi +.P +.RE +.P +would return a pointer to the string +.BR \(dqDom\(dq +if the identified language was Portuguese, and +.BR \(dqSun\(dq +if the identified language was English. +.sp +.RS 4 +.nf + +nl_langinfo_l(ABDAY_1, loc) +.fi +.P +.RE +.P +would return a pointer to the string +.BR \(dqDom\(dq +if the identified language of the locale represented by +.IR loc +was Portuguese, and +.BR \(dqSun\(dq +if the identified language of the locale represented by +.IR loc +was English. +.P +The +\fInl_langinfo\fR() +function need not be thread-safe. +.P +The behavior is undefined if the +.IR locale +argument to +\fInl_langinfo_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +In a locale where +.IR langinfo +data is not defined, these functions shall return a pointer to the +corresponding string in the POSIX locale. In all locales, these functions +shall return a pointer to an empty string if +.IR item +contains an invalid setting. +.P +The application shall not modify the string returned. The pointer +returned by +\fInl_langinfo\fR() +might be invalidated or the string content might be overwritten by a +subsequent call to +\fInl_langinfo\fR() +in any thread or to +\fInl_langinfo_l\fR() +in the same thread or the initial thread, by subsequent calls to +\fIsetlocale\fR() +with a category corresponding to the category of +.IR item +(see +.IR ) +or the category LC_ALL, or by subsequent calls to +\fIuselocale\fR() +which change the category corresponding to the category of +.IR item . +The pointer returned by +\fInl_langinfo_l\fR() +might be invalidated or the string content might be overwritten by a +subsequent call to +\fInl_langinfo_l\fR() +in the same thread or to +\fInl_langinfo\fR() +in any thread, or by subsequent calls to +\fIfreelocale\fR() +or +\fInewlocale\fR() +which free or modify the locale object that was passed to +\fInl_langinfo_l\fR(). +The returned pointer and the string content might also be +invalidated if the calling thread is terminated. +.SH "ERRORS" +No errors are defined. +.br +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting Date and Time Formatting Information" +.P +The following example returns a pointer to a string containing date and +time formatting information, as defined in the +.IR LC_TIME +category of the current locale. +.sp +.RS 4 +.nf + +#include +#include +\&... +strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The array pointed to by the return value should not be modified by the +program, but may be modified by further calls to these functions. +.SH RATIONALE +The possible interactions between internal data used by +\fInl_langinfo\fR() +and +\fInl_langinfo_l\fR() +are complicated by the fact that +\fInl_langinfo_l\fR() +must be thread-safe but +\fInl_langinfo\fR() +need not be. The various implementation choices are: +.IP " 1." 4 +\fInl_langinfo_l\fR() +and +\fInl_langinfo\fR() +use separate buffers, or at least one of them does not use an internal +string buffer. In this case there are no interactions. +.IP " 2." 4 +\fInl_langinfo_l\fR() +and +\fInl_langinfo\fR() +share an internal per-thread buffer. There can be interactions, but +only in the same thread. +.IP " 3." 4 +\fInl_langinfo_l\fR() +uses an internal per-thread buffer, and +\fInl_langinfo\fR() +uses (in all threads) the same buffer that +\fInl_langinfo_l\fR() +uses in the initial thread. There can be interactions, but only when +\fInl_langinfo_l\fR() +is called in the initial thread. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/nrand48.3p b/upstream/archlinux/man3p/nrand48.3p new file mode 100644 index 00000000..8a605162 --- /dev/null +++ b/upstream/archlinux/man3p/nrand48.3p @@ -0,0 +1,40 @@ +'\" et +.TH NRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nrand48 +\(em generate uniformly distributed pseudo-random non-negative long integers +.SH SYNOPSIS +.LP +.nf +#include +.P +long nrand48(unsigned short \fIxsubi\fP[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ntohl.3p b/upstream/archlinux/man3p/ntohl.3p new file mode 100644 index 00000000..8d6d0446 --- /dev/null +++ b/upstream/archlinux/man3p/ntohl.3p @@ -0,0 +1,42 @@ +'\" et +.TH NTOHL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ntohl, +ntohs +\(em convert values between host and network byte order +.SH SYNOPSIS +.LP +.nf +#include +.P +uint32_t ntohl(uint32_t \fInetlong\fP); +uint16_t ntohs(uint16_t \fInetshort\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIhtonl\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/open.3p b/upstream/archlinux/man3p/open.3p new file mode 100644 index 00000000..fcc898a9 --- /dev/null +++ b/upstream/archlinux/man3p/open.3p @@ -0,0 +1,794 @@ +'\" et +.TH OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +open, openat +\(em open file +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int open(const char *\fIpath\fP, int \fIoflag\fP, ...); +int openat(int \fIfd\fP, const char *\fIpath\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +The +\fIopen\fR() +function shall establish the connection between a file and a file +descriptor. It shall create an open file description that refers to a +file and a file descriptor that refers to that open file description. +The file descriptor is used by other I/O functions to refer to that +file. The +.IR path +argument points to a pathname naming the file. +.P +The +\fIopen\fR() +function shall return a file descriptor for the named file, allocated +as described in +.IR "Section 2.14" ", " "File Descriptor Allocation". +The open file description is new, and therefore the file descriptor +shall not share it with any other process in the +system. The FD_CLOEXEC file descriptor flag associated with the new +file descriptor shall be cleared unless the O_CLOEXEC flag is set in +.IR oflag . +.P +The file offset used to mark the current position within the file shall +be set to the beginning of the file. +.P +The file status flags and file access modes of the open file +description shall be set according to the value of +.IR oflag . +.P +Values for +.IR oflag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR . +Applications shall specify exactly one of the first five values +(file access modes) below in the value of +.IR oflag : +.IP O_EXEC 14 +Open for execute only (non-directory files). The result is unspecified +if this flag is applied to a directory. +.IP O_RDONLY 14 +Open for reading only. +.IP O_RDWR 14 +Open for reading and writing. The result is undefined if this flag is +applied to a FIFO. +.IP O_SEARCH 14 +Open directory for search only. The result is unspecified if this flag +is applied to a non-directory file. +.IP O_WRONLY 14 +Open for writing only. +.P +Any combination of the following may be used: +.IP O_APPEND 14 +If set, the file offset shall be set to the end of the file prior +to each write. +.IP O_CLOEXEC 14 +If set, the FD_CLOEXEC flag for the new file descriptor shall be set. +.IP O_CREAT 14 +If the file exists, this flag has no effect except as noted under O_EXCL +below. Otherwise, if O_DIRECTORY is not set the file shall be created as +a regular file; the user ID of the file shall be set to the effective +user ID of the process; the group ID of the file shall be set to +the group ID of the file's parent directory or to the effective +group ID of the process; and the access permission bits (see +.IR ) +of the file mode shall be set to the value of the argument following the +.IR oflag +argument taken as type +.BR mode_t +modified as follows: a bitwise AND is performed on the file-mode bits +and the corresponding bits in the complement of the process' file mode +creation mask. Thus, all bits in the file mode whose corresponding bit +in the file mode creation mask is set are cleared. When bits other than +the file permission bits are set, the effect is unspecified. The argument +following the +.IR oflag +argument does not affect whether the file is open for reading, writing, +or for both. Implementations shall provide a way to initialize the file's +group ID to the group ID of the parent directory. Implementations may, +but need not, provide an implementation-defined way to initialize the +file's group ID to the effective group ID of the calling process. +.IP O_DIRECTORY 14 +If +.IR path +resolves to a non-directory file, fail and set +.IR errno +to +.BR [ENOTDIR] . +.IP O_DSYNC 14 +Write I/O operations on the file descriptor shall complete as defined +by synchronized I/O data integrity completion. +.IP O_EXCL 14 +If O_CREAT and O_EXCL are set, +\fIopen\fR() +shall fail if the file exists. The check for the existence of the file +and the creation of the file if it does not exist shall be atomic with +respect to other threads executing +\fIopen\fR() +naming the same filename in the same directory with O_EXCL and O_CREAT +set. If O_EXCL and O_CREAT are set, and +.IR path +names a symbolic link, +\fIopen\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] , +regardless of the contents of the symbolic link. If O_EXCL is set and +O_CREAT is not set, the result is undefined. +.IP O_NOCTTY 14 +If set and +.IR path +identifies a terminal device, +\fIopen\fR() +shall not cause the terminal device to become the controlling terminal +for the process. If +.IR path +does not identify a terminal device, O_NOCTTY shall be ignored. +.IP O_NOFOLLOW 14 +If +.IR path +names a symbolic link, fail and set +.IR errno +to +.BR [ELOOP] . +.IP O_NONBLOCK 14 +When opening a FIFO with O_RDONLY or O_WRONLY set: +.RS 14 +.IP " *" 4 +If O_NONBLOCK is set, an +\fIopen\fR() +for reading-only shall return without delay. An +\fIopen\fR() +for writing-only shall return an error if no process currently has the +file open for reading. +.IP " *" 4 +If O_NONBLOCK is clear, an +\fIopen\fR() +for reading-only shall block the calling thread until a thread opens +the file for writing. An +\fIopen\fR() +for writing-only shall block the calling thread until a thread opens +the file for reading. +.P +When opening a block special or character special file that supports +non-blocking opens: +.IP " *" 4 +If O_NONBLOCK is set, the +\fIopen\fR() +function shall return without blocking for the device to be ready or +available. Subsequent behavior of the device is device-specific. +.IP " *" 4 +If O_NONBLOCK is clear, the +\fIopen\fR() +function shall block the calling thread until the device is ready or +available before returning. +.P +Otherwise, the O_NONBLOCK flag shall not cause an error, but it is +unspecified whether the file status flags will include the O_NONBLOCK +flag. +.RE +.IP O_RSYNC 14 +Read I/O operations on the file descriptor shall complete at the same +level of integrity as specified by the O_DSYNC and +O_SYNC flags. If both O_DSYNC and O_RSYNC are set in +.IR oflag , +all I/O operations on the file descriptor shall complete as defined by +synchronized I/O data integrity completion. If both O_SYNC and O_RSYNC +are set in flags, all I/O operations on the file descriptor shall +complete as defined by synchronized I/O file integrity completion. +.IP O_SYNC 14 +Write I/O operations on the file descriptor shall complete as defined +by synchronized I/O file integrity completion. +.RS 14 +.P +The O_SYNC flag shall be supported for regular files, even if the +Synchronized Input and Output option is not supported. +.RE +.IP O_TRUNC 14 +If the file exists and is a regular file, and the file is successfully +opened O_RDWR or O_WRONLY, its length shall be truncated to 0, and +the mode and owner shall be unchanged. It shall have no effect on FIFO +special files or terminal device files. Its effect on other file types +is implementation-defined. The result of using O_TRUNC without either +O_RDWR or O_WRONLY is undefined. +.IP O_TTY_INIT 14 +If +.IR path +identifies a terminal device other than a pseudo-terminal, the device +is not already open in any process, and either O_TTY_INIT is set in +.IR oflag +or O_TTY_INIT has the value zero, +\fIopen\fR() +shall set any non-standard +.BR termios +structure terminal parameters to a state that provides conforming +behavior; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 11.2" ", " "Parameters that Can be Set". +It is unspecified whether O_TTY_INIT has any effect if the device is +already open in any process. If +.IR path +identifies the slave side of a pseudo-terminal that is not already open +in any process, +\fIopen\fR() +shall set any non-standard +.BR termios +structure terminal parameters to a state that provides conforming +behavior, regardless of whether O_TTY_INIT is set. If +.IR path +does not identify a terminal device, O_TTY_INIT shall be ignored. +.P +If O_CREAT and O_DIRECTORY are set and the requested access mode is +neither O_WRONLY nor O_RDWR, the result is unspecified. +.P +If O_CREAT is set and the file did not previously exist, upon successful +completion, +\fIopen\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the file and the last data +modification and last file status change timestamps of the parent +directory. +.P +If O_TRUNC is set and the file did previously exist, upon successful +completion, +\fIopen\fR() +shall mark for update the last data modification and last file status +change timestamps of the file. +.P +If both the O_SYNC and O_DSYNC flags are set, the effect is as if only +the O_SYNC flag was set. +.P +If +.IR path +refers to a STREAMS file, +.IR oflag +may be constructed from O_NONBLOCK OR'ed with either O_RDONLY, O_WRONLY, +or O_RDWR. Other flag values are not applicable to STREAMS devices and +shall have no effect on them. The value O_NONBLOCK affects the operation +of STREAMS drivers and certain functions applied to file descriptors +associated with STREAMS files. For STREAMS drivers, the implementation +of O_NONBLOCK is device-specific. +.P +The application shall ensure that it specifies the O_TTY_INIT flag on the +first open of a terminal device since system boot or since the device +was closed by the process that last had it open. The application need +not specify the O_TTY_INIT flag when opening pseudo-terminals. +If +.IR path +names the master side of a pseudo-terminal device, then it is unspecified +whether +\fIopen\fR() +locks the slave side so that it cannot be opened. Conforming applications +shall call +\fIunlockpt\fR() +before opening the slave side. +.P +The largest value that can be represented correctly in an object of type +.BR off_t +shall be established as the offset maximum in the open file description. +.P +The +\fIopenat\fR() +function shall be equivalent to the +\fIopen\fR() +function except in the case where +.IR path +specifies a relative path. In this case the file to be opened is +determined relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +The +.IR oflag +parameter and the optional fourth parameter correspond exactly to the +parameters of +\fIopen\fR(). +.P +If +\fIopenat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIopen\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall open the file and +return a non-negative integer representing the file descriptor. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, no files shall be created +or modified. +.br +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or the +file exists and the permissions specified by +.IR oflag +are denied, or the file does not exist and write permission is denied +for the parent directory of the file to be created, or O_TRUNC is +specified and write permission is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set, and the named file exists. +.TP +.BR EINTR +A signal was caught during +\fIopen\fR(). +.TP +.BR EINVAL +The implementation does not support synchronized I/O for this file. +.TP +.BR EIO +The +.IR path +argument names a STREAMS file and a hangup or error occurred during the +\fIopen\fR(). +.TP +.BR EISDIR +The named file is a directory and +.IR oflag +includes O_WRONLY or O_RDWR, or includes O_CREAT without O_DIRECTORY. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument, or O_NOFOLLOW was specified and the +.IR path +argument names a symbolic link. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and a component of +.IR path +does not name an existing file, or O_CREAT is set and a component of +the path prefix of +.IR path +does not name an existing file, or +.IR path +points to an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +O_CREAT is set, and the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path +without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSR +The +.IR path +argument names a STREAMS-based file and the system is unable to +allocate a STREAM. +.TP +.BR ENOSPC +The directory or file system that would contain the new file cannot be +expanded, the file does not exist, and O_CREAT is specified. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory; or O_CREAT and O_EXCL +are not specified, the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters, and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory; or O_DIRECTORY +was specified and the +.IR path +argument resolves to a non-directory file. +.TP +.BR ENXIO +O_NONBLOCK is set, the named file is a FIFO, O_WRONLY is set, and no +process has the file open for reading. +.TP +.BR ENXIO +The named file is a character special or block special file, and the +device associated with this special file does not exist. +.TP +.BR EOVERFLOW +The named file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.TP +.BR EROFS +The named file resides on a read-only file system and either O_WRONLY, +O_RDWR, O_CREAT (if the file does not exist), or O_TRUNC is set in the +.IR oflag +argument. +.P +The +\fIopenat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for +reading or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR EAGAIN +The +.IR path +argument names the slave side of a pseudo-terminal device that is locked. +.TP +.BR EINVAL +The value of the +.IR oflag +argument is not valid. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOMEM +The +.IR path +argument names a STREAMS file and the system is unable to allocate +resources. +.TP +.BR EOPNOTSUPP +The +.IR path +argument names a socket. +.TP +.BR ETXTBSY +The file is a pure procedure (shared text) file that is being executed +and +.IR oflag +is O_WRONLY or O_RDWR. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Opening a File for Writing by the Owner" +.P +The following example opens the file +.BR /tmp/file , +either by creating it (if it does not already exist), or by truncating +its length to 0 (if it does exist). In the former case, if the call +creates a new file, the access permission bits in the file mode of the +file are set to permit reading and writing by the owner, and to permit +reading only by group members and others. +.P +If the call to +\fIopen\fR() +is successful, the file is opened for writing. +.sp +.RS 4 +.nf + +#include +\&... +int fd; +mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH; +char *pathname = "/tmp/file"; +\&... +fd = open(pathname, O_WRONLY | O_CREAT | O_TRUNC, mode); +\&... +.fi +.P +.RE +.SS "Opening a File Using an Existence Check" +.P +The following example uses the +\fIopen\fR() +function to try to create the +.BR LOCKFILE +file and open it for writing. Since the +\fIopen\fR() +function specifies the O_EXCL flag, the call fails if the file already +exists. In that case, the program assumes that someone else is updating +the password file and exits. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; /* Integer for file descriptor returned by open() call. */ +\&... +if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en"); + exit(1); +} +\&... +.fi +.P +.RE +.SS "Opening a File for Writing" +.P +The following example opens a file for writing, creating the file if it +does not already exist. If the file does exist, the system truncates +the file to zero bytes. +.sp +.RS 4 +.nf + +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +\&... +int pfd; +char pathname[PATH_MAX+1]; +\&... +if ((pfd = open(pathname, O_WRONLY | O_CREAT | O_TRUNC, + S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) +{ + perror("Cannot open output file\en"); exit(1); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +POSIX.1\(hy2008 does not require that terminal parameters be automatically set to +any state on first open, nor that they be reset after the last close. It +is possible for a non-conforming application to leave a terminal device +in a state where the next process to use that device finds it in a +non-conforming state, but has no way of determining this. To ensure +that the device is set to a conforming initial state, applications which +perform a first open of a terminal (other than a pseudo-terminal) should +do so using the O_TTY_INIT flag to set the parameters associated with +the terminal to a conforming state. +.P +Except as specified in this volume of POSIX.1\(hy2017, the flags allowed in +.IR oflag +are not mutually-exclusive and any number of them may be used +simultaneously. Not all combinations of flags make sense. For example, +using O_SEARCH | O_CREAT will successfully open a pre-existing directory +for searching, but if there is no existing file by that name, then +it is unspecified whether a regular file will be created. Likewise, +if a non-directory file descriptor is successfully returned, it is +unspecified whether that descriptor will have execute permissions as if +by O_EXEC (note that it is unspecified whether O_EXEC and O_SEARCH have +the same value). +.SH RATIONALE +Some implementations permit opening FIFOs with O_RDWR. Since FIFOs could +be implemented in other ways, and since two file descriptors can be used +to the same effect, this possibility is left as undefined. +.P +See +.IR "\fIgetgroups\fR\^(\|)" +about the group of a newly created file. +.P +The use of +\fIopen\fR() +to create a regular file is preferable to the use of +\fIcreat\fR(), +because the latter is redundant and included only for historical +reasons. +.P +The use of the O_TRUNC flag on FIFOs and directories (pipes cannot be +\fIopen\fR()-ed) +must be permissible without unexpected side-effects (for example, +\fIcreat\fR() +on a FIFO must not remove data). Since terminal special files might have +type-ahead data stored in the buffer, O_TRUNC should not affect their +content, particularly if a program that normally opens a regular file +should open the current controlling terminal instead. Other file types, +particularly implementation-defined ones, are left implementation-defined. +.P +POSIX.1\(hy2008 permits +.BR [EACCES] +to be returned for conditions other than those explicitly listed. +.P +The O_NOCTTY flag was added to allow applications to avoid unintentionally +acquiring a controlling terminal as a side-effect of opening a terminal +file. This volume of POSIX.1\(hy2017 does not specify how a controlling terminal is acquired, +but it allows an implementation to provide this on +\fIopen\fR() +if the O_NOCTTY flag is not set and other conditions specified in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface" +are met. +.P +In historical implementations the value of O_RDONLY is zero. Because of +that, it is not possible to detect the presence of O_RDONLY and another +option. Future implementations should encode O_RDONLY and O_WRONLY as +bit flags so that: +.sp +.RS 4 +.nf + +O_RDONLY | O_WRONLY == O_RDWR +.fi +.P +.RE +.P +O_EXEC and O_SEARCH are specified as two of the five file access modes. +Since O_EXEC does not apply to directories, and O_SEARCH only applies +to directories, their values need not be distinct. Since O_RDONLY +has historically had the value zero, implementations are not able to +distinguish between O_SEARCH and O_SEARCH | O_RDONLY, and similarly +for O_EXEC. +.P +In general, the +\fIopen\fR() +function follows the symbolic link if +.IR path +names a symbolic link. However, the +\fIopen\fR() +function, when called with O_CREAT and O_EXCL, is required to fail with +.BR [EEXIST] +if +.IR path +names an existing symbolic link, even if the symbolic link refers +to a nonexistent file. This behavior is required so that privileged +applications can create a new file in a known location without the +possibility that a symbolic link might cause the file to be created in +a different location. +.P +For example, a privileged application that must create a file with a +predictable name in a user-writable directory, such as the user's home +directory, could be compromised if the user creates a symbolic link +with that name that refers to a nonexistent file in a system +directory. If the user can influence the contents of a file, the user +could compromise the system by creating a new system configuration or +spool file that would then be interpreted by the system. The test for a +symbolic link which refers to a nonexisting file must be atomic with +the creation of a new file. +.P +In addition, the +\fIopen\fR() +function refuses to open non-directories if the O_DIRECTORY flag is +set. This avoids race conditions whereby a user might compromise the +system by substituting a hard link to a sensitive file (e.g., a device +or a FIFO) while a privileged application is running, where opening a +file even for read access might have undesirable side-effects. +.P +In addition, the +\fIopen\fR() +function does not follow symbolic links if the O_NOFOLLOW flag is set. +This avoids race conditions whereby a user might compromise the system +by substituting a symbolic link to a sensitive file (e.g., a device) +while a privileged application is running, where opening a file even +for read access might have undesirable side-effects. +.P +The POSIX.1\(hy1990 standard required that the group ID of a newly created file be set to +the group ID of its parent directory or to the effective group ID of +the creating process. FIPS 151\(hy2 required that implementations provide a way +to have the group ID be set to the group ID of the containing +directory, but did not prohibit implementations also supporting a way +to set the group ID to the effective group ID of the creating process. +Conforming applications should not assume which group ID will be used. If +it matters, an application can use +\fIchown\fR() +to set the group ID after the file is created, or determine under what +conditions the implementation will set the desired group ID. +.P +The purpose of the +\fIopenat\fR() +function is to enable opening files in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIopen\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIopenat\fR() +function it can be guaranteed that the opened file is located relative +to the desired directory. Some implementations use the +\fIopenat\fR() +function for other purposes as well. In some cases, if the +.IR oflag +parameter has the O_XATTR bit set, the returned file descriptor provides +access to extended attributes. This functionality is not standardized +here. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIumask\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/open_memstream.3p b/upstream/archlinux/man3p/open_memstream.3p new file mode 100644 index 00000000..7ddf3c1e --- /dev/null +++ b/upstream/archlinux/man3p/open_memstream.3p @@ -0,0 +1,204 @@ +'\" et +.TH OPEN_MEMSTREAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +open_memstream, open_wmemstream +\(em open a dynamic memory buffer stream +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *open_memstream(char **\fIbufp\fP, size_t *\fIsizep\fP); +.P +#include +.P +FILE *open_wmemstream(wchar_t **\fIbufp\fP, size_t *\fIsizep\fP); +.fi +.SH DESCRIPTION +The +\fIopen_memstream\fR() +and +\fIopen_wmemstream\fR() +functions shall create an I/O stream associated with a dynamically +allocated memory buffer. The stream shall be opened for writing and +shall be seekable. +.P +The stream associated with a call to +\fIopen_memstream\fR() +shall be byte-oriented. +.P +The stream associated with a call to +\fIopen_wmemstream\fR() +shall be wide-oriented. +.P +The stream shall maintain a current position in the allocated buffer +and a current buffer length. The position shall be initially set to +zero (the start of the buffer). Each write to the stream shall start at +the current position and move this position by the number of +successfully written bytes for +\fIopen_memstream\fR() +or the number of successfully written wide characters for +\fIopen_wmemstream\fR(). +The length shall be initially set to zero. If a write moves the +position to a value larger than the current length, the current length +shall be set to this position. In this case a null character for +\fIopen_memstream\fR() +or a null wide character for +\fIopen_wmemstream\fR() +shall be appended to the current buffer. For both functions the +terminating null is not included in the calculation of the buffer +length. +.P +After a successful +\fIfflush\fR() +or +\fIfclose\fR(), +the pointer referenced by +.IR bufp +shall contain the address of the buffer, and the variable pointed to by +.IR sizep +shall contain the smaller of the current buffer length and the +number of bytes for +\fIopen_memstream\fR(), +or the number of wide characters for +\fIopen_wmemstream\fR(), +between the beginning of the buffer and the current file position indicator. +.P +After a successful +\fIfflush\fR() +the pointer referenced by +.IR bufp +and the variable referenced by +.IR sizep +remain valid only until the next write operation on the stream or a +call to +\fIfclose\fR(). +.P +After a successful +\fIfclose\fR(), +the pointer referenced by +.IR bufp +can be passed to +\fIfree\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a pointer to +the object controlling the stream. Otherwise, a null pointer shall be +returned, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.P +These functions may fail if: +.TP +.BR EINVAL +.IR bufp +or +.IR sizep +are NULL. +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENOMEM +Memory for the stream or the buffer could not be allocated. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.sp +.RS 4 +.nf + +#include +#include +.P +int +main (void) +{ + FILE *stream; + char *buf; + size_t len; + off_t eob; +.P + stream = open_memstream (&buf, &len); + if (stream == NULL) + /* handle error */ ; + fprintf (stream, "hello my world"); + fflush (stream); + printf ("buf=%s, len=%zu\en", buf, len); + eob = ftello(stream); + fseeko (stream, 0, SEEK_SET); + fprintf (stream, "good-bye"); + fseeko (stream, eob, SEEK_SET); + fclose (stream); + printf ("buf=%s, len=%zu\en", buf, len); + free (buf); + return 0; +} +.fi +.P +.RE +.P +This program produces the following output: +.sp +.RS 4 +.nf + +buf=hello my world, len=14 +buf=good-bye world, len=14 +.fi +.P +.RE +.SH "APPLICATION USAGE" +The buffer created by these functions should be freed by the +application after closing the stream, by means of a call to +\fIfree\fR(). +.SH RATIONALE +These functions are similar to +\fIfmemopen\fR() +except that the memory is always allocated dynamically by the function, +and the stream is opened only for output. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfdopen\fR\^(\|)", +.IR "\fIfflush\fR\^(\|)", +.IR "\fIfmemopen\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIfreopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/openat.3p b/upstream/archlinux/man3p/openat.3p new file mode 100644 index 00000000..c38a8480 --- /dev/null +++ b/upstream/archlinux/man3p/openat.3p @@ -0,0 +1,40 @@ +'\" et +.TH OPENAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +openat +\(em open file relative to directory file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +int openat(int \fIfd\fP, const char *\fIpath\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIopen\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/opendir.3p b/upstream/archlinux/man3p/opendir.3p new file mode 100644 index 00000000..0149bd1a --- /dev/null +++ b/upstream/archlinux/man3p/opendir.3p @@ -0,0 +1,40 @@ +'\" et +.TH OPENDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +opendir +\(em open directory associated with file descriptor +.SH SYNOPSIS +.LP +.nf +#include +.P +DIR *opendir(const char *\fIdirname\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfdopendir\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/openlog.3p b/upstream/archlinux/man3p/openlog.3p new file mode 100644 index 00000000..1d3f80cd --- /dev/null +++ b/upstream/archlinux/man3p/openlog.3p @@ -0,0 +1,40 @@ +'\" et +.TH OPENLOG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +openlog +\(em open a connection to the logging facility +.SH SYNOPSIS +.LP +.nf +#include +.P +void openlog(const char *\fIident\fP, int \fIlogopt\fP, int \fIfacility\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcloselog\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/optarg.3p b/upstream/archlinux/man3p/optarg.3p new file mode 100644 index 00000000..c53f57c7 --- /dev/null +++ b/upstream/archlinux/man3p/optarg.3p @@ -0,0 +1,44 @@ +'\" et +.TH OPTARG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +optarg, +opterr, +optind, +optopt +\(em options parsing variables +.SH SYNOPSIS +.LP +.nf +#include +.P +extern char *optarg; +extern int opterr, optind, optopt; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetopt\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pathconf.3p b/upstream/archlinux/man3p/pathconf.3p new file mode 100644 index 00000000..f4cdb68a --- /dev/null +++ b/upstream/archlinux/man3p/pathconf.3p @@ -0,0 +1,40 @@ +'\" et +.TH PATHCONF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pathconf +\(em get configurable pathname variables +.SH SYNOPSIS +.LP +.nf +#include +.P +long pathconf(const char *\fIpath\fP, int \fIname\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfpathconf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pause.3p b/upstream/archlinux/man3p/pause.3p new file mode 100644 index 00000000..72a9e5b5 --- /dev/null +++ b/upstream/archlinux/man3p/pause.3p @@ -0,0 +1,93 @@ +'\" et +.TH PAUSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pause +\(em suspend the thread until a signal is received +.SH SYNOPSIS +.LP +.nf +#include +.P +int pause(void); +.fi +.SH DESCRIPTION +The +\fIpause\fR() +function shall suspend the calling thread until delivery of a signal +whose action is either to execute a signal-catching function or to +terminate the process. +.P +If the action is to terminate the process, +\fIpause\fR() +shall not return. +.P +If the action is to execute a signal-catching function, +\fIpause\fR() +shall return after the signal-catching function returns. +.SH "RETURN VALUE" +Since +\fIpause\fR() +suspends thread execution indefinitely unless interrupted by a signal, +there is no successful completion return value. A value of \-1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIpause\fR() +function shall fail if: +.TP +.BR EINTR +A signal is caught by the calling process and control is returned from +the signal-catching function. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Many common uses of +\fIpause\fR() +have timing windows. The scenario involves checking a condition +related to a signal and, if the signal has not occurred, calling +\fIpause\fR(). +When the signal occurs between the check and the call to +\fIpause\fR(), +the process often blocks indefinitely. The +\fIsigprocmask\fR() +and +\fIsigsuspend\fR() +functions can be used to avoid this type of problem. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pclose.3p b/upstream/archlinux/man3p/pclose.3p new file mode 100644 index 00000000..b9c81747 --- /dev/null +++ b/upstream/archlinux/man3p/pclose.3p @@ -0,0 +1,227 @@ +'\" et +.TH PCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pclose +\(em close a pipe stream to or from a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int pclose(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The +\fIpclose\fR() +function shall close a stream that was opened by +\fIpopen\fR(), +wait for the command to terminate, and return the termination status +of the process that was running the command language interpreter. +However, if a call caused the termination status to be unavailable to +\fIpclose\fR(), +then +\fIpclose\fR() +shall return \-1 with +.IR errno +set to +.BR [ECHILD] +to report this situation. This can happen if the application calls one +of the following functions: +.IP " *" 4 +\fIwait\fR() +.IP " *" 4 +\fIwaitpid\fR() +with a +.IR pid +argument less than or equal to 0 or equal to the process ID of the +command line interpreter +.IP " *" 4 +Any other function not defined in this volume of POSIX.1\(hy2017 that could do one of the above +.P +In any case, +\fIpclose\fR() +shall not return before the child process created by +\fIpopen\fR() +has terminated. +.P +If the command language interpreter cannot be executed, the child +termination status returned by +\fIpclose\fR() +shall be as if the command language interpreter terminated using +.IR exit (127) +or +.IR _exit (127). +.P +The +\fIpclose\fR() +function shall not affect the termination status of any child of the +calling process other than the one created by +\fIpopen\fR() +for the associated stream. +.P +If the argument +.IR stream +to +\fIpclose\fR() +is not a pointer to a stream created by +\fIpopen\fR(), +the result of +\fIpclose\fR() +is undefined. +.P +If a thread is canceled during execution of +\fIpclose\fR(), +the behavior is undefined. +.SH "RETURN VALUE" +Upon successful return, +\fIpclose\fR() +shall return the termination status of the command language +interpreter. Otherwise, +\fIpclose\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIpclose\fR() +function shall fail if: +.TP +.BR ECHILD +The status of the child process could not be obtained, as described +above. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +There is a requirement that +\fIpclose\fR() +not return before the child process terminates. This is intended to +disallow implementations that return +.BR [EINTR] +if a signal is received while waiting. If +\fIpclose\fR() +returned before the child terminated, there would be no way for the +application to discover which child used to be associated with the +stream, and it could not do the cleanup itself. +.P +If the stream pointed to by +.IR stream +was not created by +\fIpopen\fR(), +historical implementations of +\fIpclose\fR() +return \-1 without setting +.IR errno . +To avoid requiring +\fIpclose\fR() +to set +.IR errno +in this case, POSIX.1\(hy2008 makes the behavior unspecified. An application +should not use +\fIpclose\fR() +to close any stream that was not created by +\fIpopen\fR(). +.P +Some historical implementations of +\fIpclose\fR() +either block or ignore the signals SIGINT, SIGQUIT, and SIGHUP while +waiting for the child process to terminate. Since this behavior is not +described for the +\fIpclose\fR() +function in POSIX.1\(hy2008, such implementations are not conforming. Also, some +historical implementations return +.BR [EINTR] +if a signal is received, even though the child process has not +terminated. Such implementations are also considered non-conforming. +.P +Consider, for example, an application that uses: +.sp +.RS 4 +.nf + +popen("command", "r") +.fi +.P +.RE +.P +to start +.IR command , +which is part of the same application. The parent writes a prompt to +its standard output (presumably the terminal) and then reads from the +\fIpopen\fR()ed +stream. The child reads the response from the user, does some +transformation on the response (pathname expansion, perhaps) and +writes the result to its standard output. The parent process reads the +result from the pipe, does something with it, and prints another +prompt. The cycle repeats. Assuming that both processes do appropriate +buffer flushing, this would be expected to work. +.P +To conform to POSIX.1\(hy2008, +\fIpclose\fR() +must use +\fIwaitpid\fR(), +or some similar function, instead of +\fIwait\fR(). +.P +The code sample below illustrates how the +\fIpclose\fR() +function might be implemented on a system conforming to POSIX.1\(hy2008. +.sp +.RS 4 +.nf + +int pclose(FILE *stream) +{ + int stat; + pid_t pid; +.P + pid = + (void) fclose(stream); + while (waitpid(pid, &stat, 0) == -1) { + if (errno != EINTR){ + stat = -1; + break; + } + } + return(stat); +} +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfork\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/perror.3p b/upstream/archlinux/man3p/perror.3p new file mode 100644 index 00000000..9d60c624 --- /dev/null +++ b/upstream/archlinux/man3p/perror.3p @@ -0,0 +1,158 @@ +'\" et +.TH PERROR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +perror +\(em write error messages to standard error +.SH SYNOPSIS +.LP +.nf +#include +.P +void perror(const char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIperror\fR() +function shall map the error number accessed through the symbol +.IR errno +to a language-dependent error message, which shall be written to the +standard error stream as follows: +.IP " *" 4 +First (if +.IR s +is not a null pointer and the character pointed to by +.IR s +is not the null byte), the string pointed to by +.IR s +followed by a + +and a +. +.IP " *" 4 +Then an error message string followed by a +. +.P +The contents of the error message strings shall be the same as those +returned by +\fIstrerror\fR() +with argument +.IR errno . +.P +The +\fIperror\fR() +function shall mark for update the last data modification and last file +status change timestamps of the file associated with the standard error +stream at some time between its successful completion and +\fIexit\fR(), +\fIabort\fR(), +or the completion of +\fIfflush\fR() +or +\fIfclose\fR() +on +.IR stderr . +.P +The +\fIperror\fR() +function shall not change the orientation of the standard error stream. +.P +On error, +\fIperror\fR() +shall set the error indicator for the stream to which +.IR stderr +points, and shall set +.IR errno +to indicate the error. +.P +Since no value is returned, an application wishing to check for error +situations should call +.IR clearerr ( stderr ) +before calling +\fIperror\fR(), +then if +.IR ferror ( stderr ) +returns non-zero, the value of +.IR errno +indicates which error occurred. +.SH "RETURN VALUE" +The +\fIperror\fR() +function shall not return a value. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Printing an Error Message for a Function" +.P +The following example replaces +.IR bufptr +with a buffer that is the necessary size. If an error occurs, the +\fIperror\fR() +function prints a message and the program exits. +.sp +.RS 4 +.nf + +#include +#include +\&... +char *bufptr; +size_t szbuf; +\&... +if ((bufptr = malloc(szbuf)) == NULL) { + perror("malloc"); exit(2); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Application writers may prefer to use alternative interfaces instead of +\fIperror\fR(), +such as +\fIstrerror_r\fR() +in combination with +\fIfprintf\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfputc\fR\^(\|)", +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIstrerror\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pipe.3p b/upstream/archlinux/man3p/pipe.3p new file mode 100644 index 00000000..a56a498c --- /dev/null +++ b/upstream/archlinux/man3p/pipe.3p @@ -0,0 +1,174 @@ +'\" et +.TH PIPE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pipe +\(em create an interprocess channel +.SH SYNOPSIS +.LP +.nf +#include +.P +int pipe(int \fIfildes\fP[2]); +.fi +.SH DESCRIPTION +The +\fIpipe\fR() +function shall create a pipe and place two file descriptors, one +each into the arguments +.IR fildes [0] +and +.IR fildes [1], +that refer to the open file descriptions for the read and write ends of +the pipe. The file descriptors shall be allocated as described in +.IR "Section 2.14" ", " "File Descriptor Allocation". +The O_NONBLOCK and FD_CLOEXEC flags shall be clear on both file +descriptors. (The +\fIfcntl\fR() +function can be used to set both these flags.) +.P +Data can be written to the file descriptor +.IR fildes [1] +and read from the file descriptor +.IR fildes [0]. +A read on the file descriptor +.IR fildes [0] +shall access data written to the file descriptor +.IR fildes [1] +on a first-in-first-out basis. It is unspecified whether +.IR fildes [0] +is also open for writing and whether +.IR fildes [1] +is also open for reading. +.P +A process has the pipe open for reading (correspondingly writing) if it +has a file descriptor open that refers to the read end, +.IR fildes [0] +(write end, +.IR fildes [1]). +.P +The pipe's user ID shall be set to the effective user ID of the +calling process. +.P +The pipe's group ID shall be set to the effective group ID of the +calling process. +.P +Upon successful completion, +\fIpipe\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the pipe. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \-1 shall +be returned and +.IR errno +set to indicate the error, no file descriptors shall be allocated and +the contents of +.IR fildes +shall be left unmodified. +.SH ERRORS +The +\fIpipe\fR() +function shall fail if: +.TP +.BR EMFILE +All, or all but one, of the file descriptors available to the process +are currently open. +.TP +.BR ENFILE +The number of simultaneously open files in the system would exceed a +system-imposed limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using a Pipe to Pass Data Between a Parent Process and a Child Process" +.P +The following example demonstrates the use of a pipe to transfer data +between a parent process and a child process. Error handling is +excluded, but otherwise this code demonstrates good practice when using +pipes: after the +\fIfork\fR() +the two processes close the unused ends of the pipe before they +commence transferring data. +.sp +.RS 4 +.nf + +#include +#include +\&... +.P +int fildes[2]; +const int BSIZE = 100; +char buf[BSIZE]; +ssize_t nbytes; +int status; +.P +status = pipe(fildes); +if (status == -1 ) { + /* an error occurred */ + ... +} +.P +switch (fork()) { +case -1: /* Handle error */ + break; +.P +case 0: /* Child - reads from pipe */ + close(fildes[1]); /* Write end is unused */ + nbytes = read(fildes[0], buf, BSIZE); /* Get data from pipe */ + /* At this point, a further read would see end-of-file ... */ + close(fildes[0]); /* Finished with pipe */ + exit(EXIT_SUCCESS); +.P +default: /* Parent - writes to pipe */ + close(fildes[0]); /* Read end is unused */ + write(fildes[1], "Hello world\en", 12); /* Write data on pipe */ + close(fildes[1]); /* Child will see EOF */ + exit(EXIT_SUCCESS); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The wording carefully avoids using the verb ``to open'' in order to +avoid any implication of use of +\fIopen\fR(); +see also +\fIwrite\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "File Descriptor Allocation", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/poll.3p b/upstream/archlinux/man3p/poll.3p new file mode 100644 index 00000000..d270ac42 --- /dev/null +++ b/upstream/archlinux/man3p/poll.3p @@ -0,0 +1,401 @@ +'\" et +.TH POLL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +poll +\(em input/output multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +int poll(struct pollfd \fIfds\fP[], nfds_t \fInfds\fP, int \fItimeout\fP); +.fi +.SH DESCRIPTION +The +\fIpoll\fR() +function provides applications with a mechanism for multiplexing +input/output over a set of file descriptors. For each member of the +array pointed to by +.IR fds , +\fIpoll\fR() +shall examine the given file descriptor for the event(s) specified in +.IR events . +The number of +.BR pollfd +structures in the +.IR fds +array is specified by +.IR nfds . +The +\fIpoll\fR() +function shall identify those file descriptors on which an application +can read or write data, or on which certain events have occurred. +.P +The +.IR fds +argument specifies the file descriptors to be examined +and the events of interest for each file descriptor. It is a pointer to +an array with one member for each open file descriptor of interest. The +array's members are +.BR pollfd +structures within which +.IR fd +specifies an open file descriptor and +.IR events +and +.IR revents +are bitmasks constructed by OR'ing a combination of the following event +flags: +.IP POLLIN 12 +Data other than high-priority data may be read without blocking. +.RS 12 +.P +For STREAMS, this flag is set in +.IR revents +even if the message is of zero length. This flag shall be equivalent +to POLLRDNORM | POLLRDBAND. +.RE +.IP POLLRDNORM 12 +Normal data may be read without blocking. +.RS 12 +.P +For STREAMS, data on priority band 0 may be read without blocking. This +flag is set in +.IR revents +even if the message is of zero length. +.RE +.IP POLLRDBAND 12 +Priority data may be read without blocking. +.RS 12 +.P +For STREAMS, data on priority bands greater than 0 may be read without +blocking. This flag is set in +.IR revents +even if the message is of zero length. +.RE +.IP POLLPRI 12 +High-priority data may be read without blocking. +.RS 12 +.P +For STREAMS, this flag is set in +.IR revents +even if the message is of zero length. +.RE +.IP POLLOUT 12 +Normal data may be written without blocking. +.RS 12 +.P +For STREAMS, data on priority band 0 may be written without blocking. +.RE +.IP POLLWRNORM 12 +Equivalent to POLLOUT. +.IP POLLWRBAND 12 +Priority data may be written. +.RS 12 +.P +For STREAMS, data on priority bands greater than 0 may be written +without blocking. If any priority band has been written to on this +STREAM, this event only examines bands that have been written +to at least once. +.RE +.IP POLLERR 12 +An error has occurred on the device or stream. This flag is only valid +in the +.IR revents +bitmask; it shall be ignored in the +.IR events +member. +.IP POLLHUP 12 +A device has been disconnected, or a pipe or FIFO has been closed by the +last process that had it open for writing. Once set, the hangup state of a +FIFO shall persist until some process opens the FIFO for writing or until +all read-only file descriptors for the FIFO are closed. This event and +POLLOUT are mutually-exclusive; a stream can never be writable if a hangup +has occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, +or POLLPRI are not mutually-exclusive. This flag is only valid in the +.IR revents +bitmask; it shall be ignored in the +.IR events +member. +.IP POLLNVAL 12 +The specified +.IR fd +value is invalid. This flag is only valid in the +.IR revents +member; it shall ignored in the +.IR events +member. +.P +The significance and semantics of normal, priority, and high-priority +data are file and device-specific. +.P +If the value of +.IR fd +is less than 0, +.IR events +shall be ignored, and +.IR revents +shall be set to 0 in that entry on return from +\fIpoll\fR(). +.P +In each +.BR pollfd +structure, +\fIpoll\fR() +shall clear the +.IR revents +member, except that where the application requested a report on a +condition by setting one of the bits of +.IR events +listed above, +\fIpoll\fR() +shall set the corresponding bit in +.IR revents +if the requested condition is true. In addition, +\fIpoll\fR() +shall set the POLLHUP, POLLERR, and POLLNVAL flag in +.IR revents +if the condition is true, even if the application did not set the +corresponding bit in +.IR events . +.P +If none of the defined events have occurred on any selected file +descriptor, +\fIpoll\fR() +shall wait at least +.IR timeout +milliseconds for an event to occur on any of the selected file +descriptors. If the value of +.IR timeout +is 0, +\fIpoll\fR() +shall return immediately. If the value of +.IR timeout +is \-1, +\fIpoll\fR() +shall block until a requested event occurs or until the call is +interrupted. +.P +Implementations may place limitations on the granularity of timeout +intervals. If the requested timeout interval requires a finer +granularity than the implementation supports, the actual timeout +interval shall be rounded up to the next supported value. +.P +The +\fIpoll\fR() +function shall not be affected by the O_NONBLOCK flag. +.P +The +\fIpoll\fR() +function shall support regular files, terminal and pseudo-terminal +devices, FIFOs, pipes, sockets and +STREAMS-based files. +The behavior of +\fIpoll\fR() +on elements of +.IR fds +that refer to other types of file is unspecified. +.P +Regular files shall always poll TRUE for reading and writing. +.P +A file descriptor for a socket that is listening for connections shall +indicate that it is ready for reading, once connections are available. +A file descriptor for a socket that is connecting asynchronously shall +indicate that it is ready for writing, once a connection has been +established. +.P +Provided the application does not perform any action that results in +unspecified or undefined behavior, the value of the +.IR fd +and +.IR events +members of each element of +.IR fds +shall not be modified by +\fIpoll\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIpoll\fR() +shall return a non-negative value. A positive value indicates the total +number of +.BR pollfd +structures that have selected events (that is, those for which the +.IR revents +member is non-zero). A value of 0 indicates that the call timed out and +no file descriptors have been selected. Upon failure, +\fIpoll\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIpoll\fR() +function shall fail if: +.TP +.BR EAGAIN +The allocation of internal data structures failed but a subsequent +request may succeed. +.TP +.BR EINTR +A signal was caught during +\fIpoll\fR(). +.TP +.BR EINVAL +The +.IR nfds +argument is greater than +{OPEN_MAX}, +or one of the +.IR fd +members refers to a STREAM or multiplexer that is linked (directly or +indirectly) downstream from a multiplexer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Checking for Events on a Stream" +.P +The following example opens a pair of STREAMS devices and then waits +for either one to become writable. This example proceeds as follows: +.IP " 1." 4 +Sets the +.IR timeout +parameter to 500 milliseconds. +.IP " 2." 4 +Opens the STREAMS devices +.BR /dev/dev0 +and +.BR /dev/dev1 , +and then polls them, specifying POLLOUT and POLLWRBAND as the events of +interest. +.RS 4 +.P +The STREAMS device names +.BR /dev/dev0 +and +.BR /dev/dev1 +are only examples of how STREAMS devices can be named; STREAMS naming +conventions may vary among systems conforming to the POSIX.1\(hy2008. +.RE +.IP " 3." 4 +Uses the +.IR ret +variable to determine whether an event has occurred on either of the +two STREAMS. The +\fIpoll\fR() +function is given 500 milliseconds to wait for an event to occur (if it +has not occurred prior to the +\fIpoll\fR() +call). +.IP " 4." 4 +Checks the returned value of +.IR ret . +If a positive value is returned, one of the following can be done: +.RS 4 +.IP " a." 4 +Priority data can be written to the open STREAM on priority bands +greater than 0, because the POLLWRBAND event occurred on the open +STREAM (\c +.IR fds [0] +or +.IR fds [1]). +.IP " b." 4 +Data can be written to the open STREAM on priority-band 0, because the +POLLOUT event occurred on the open STREAM (\c +.IR fds [0] +or +.IR fds [1]). +.RE +.IP " 5." 4 +If the returned value is not a positive value, permission to write data +to the open STREAM (on any priority band) is denied. +.IP " 6." 4 +If the POLLHUP event occurs on the open STREAM (\c +.IR fds [0] +or +.IR fds [1]), +the device on the open STREAM has disconnected. +.sp +.RS 4 +.nf + +#include +#include +\&... +struct pollfd fds[2]; +int timeout_msecs = 500; +int ret; + int i; +.P +/* Open STREAMS device. */ +fds[0].fd = open("/dev/dev0", ...); +fds[1].fd = open("/dev/dev1", ...); +fds[0].events = POLLOUT | POLLWRBAND; +fds[1].events = POLLOUT | POLLWRBAND; +.P +ret = poll(fds, 2, timeout_msecs); +.P +if (ret > 0) { + /* An event on one of the fds has occurred. */ + for (i=0; i<2; i++) { + if (fds[i].revents & POLLWRBAND) { + /* Priority data may be written on device number i. */ +\&... + } + if (fds[i].revents & POLLOUT) { + /* Data may be written on device number i. */ +\&... + } + if (fds[i].revents & POLLHUP) { + /* A hangup has occurred on device number i. */ +\&... + } + } +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The POLLHUP event does not occur for FIFOs just because the FIFO is not +open for writing. It only occurs when the FIFO is closed by the last +writer and persists until some process opens the FIFO for writing or +until all read-only file descriptors for the FIFO are closed. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIputmsg\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/popen.3p b/upstream/archlinux/man3p/popen.3p new file mode 100644 index 00000000..35b29ceb --- /dev/null +++ b/upstream/archlinux/man3p/popen.3p @@ -0,0 +1,314 @@ +'\" et +.TH POPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +popen +\(em initiate pipe streams to or from a process +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *popen(const char *\fIcommand\fP, const char *\fImode\fP); +.fi +.SH DESCRIPTION +The +\fIpopen\fR() +function shall execute the command specified by the string +.IR command . +It shall create a pipe between the calling program and the executed +command, and shall return a pointer to a stream that can be used to +either read from or write to the pipe. +.P +The environment of the executed command shall be as if a child process +were created within the +\fIpopen\fR() +call using the +\fIfork\fR() +function, and the child invoked the +.IR sh +utility using the call: +.sp +.RS 4 +.nf + +execl(\fIshell path\fP, "sh", "-c", \fIcommand\fP, (char *)0); +.fi +.P +.RE +.P +where +.IR "shell path" +is an unspecified pathname for the +.IR sh +utility. +.P +The +\fIpopen\fR() +function shall ensure that any streams from previous +\fIpopen\fR() +calls that remain open in the parent process are closed in the new +child process. +.P +The +.IR mode +argument to +\fIpopen\fR() +is a string that specifies I/O mode: +.IP " 1." 4 +If +.IR mode +is +.IR r , +when the child process is started, its file descriptor STDOUT_FILENO +shall be the writable end of the pipe, and the file descriptor +\fIfileno\fR(\fIstream\fR) in the calling process, where +.IR stream +is the stream pointer returned by +\fIpopen\fR(), +shall be the readable end of the pipe. +.IP " 2." 4 +If +.IR mode +is +.IR w , +when the child process is started its file descriptor STDIN_FILENO +shall be the readable end of the pipe, and the file descriptor +\fIfileno\fR(\fIstream\fR) in the calling process, where +.IR stream +is the stream pointer returned by +\fIpopen\fR(), +shall be the writable end of the pipe. +.IP " 3." 4 +If +.IR mode +is any other value, the result is unspecified. +.P +After +\fIpopen\fR(), +both the parent and the child process shall be capable of executing +independently before either terminates. +.P +Pipe streams are byte-oriented. +.SH "RETURN VALUE" +Upon successful completion, +\fIpopen\fR() +shall return a pointer to an open stream that can be used to read +or write to the pipe. Otherwise, it shall return a null pointer and +may set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIpopen\fR() +function shall fail if: +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.P +The +\fIpopen\fR() +function may fail if: +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR EINVAL +The +.IR mode +argument is invalid. +.P +The +\fIpopen\fR() +function may also set +.IR errno +values as described by +.IR "\fIfork\fR\^(\|)" +or +.IR "\fIpipe\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Using popen(\|) to Obtain a List of Files from the ls Utility" +.P +The following example demonstrates the use of +\fIpopen\fR() +and +\fIpclose\fR() +to execute the command +.IR ls * +in order to obtain a list of files in the current directory: +.sp +.RS 4 +.nf + +#include +\&... +.P +FILE *fp; +int status; +char path[PATH_MAX]; +.P +fp = popen("ls *", "r"); +if (fp == NULL) + /* Handle error */; +.P +while (fgets(path, PATH_MAX, fp) != NULL) + printf("%s", path); +.P +status = pclose(fp); +if (status == -1) { + /* Error reported by pclose() */ + ... +} else { + /* Use macros described under wait() to inspect `status\(aq in order + to determine success/failure of command executed by popen() */ + ... +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +Since open files are shared, a mode +.IR r +command can be used as an input filter and a mode +.IR w +command as an output filter. +.P +Buffered reading before opening an input filter may leave the standard +input of that filter mispositioned. Similar problems with an output +filter may be prevented by careful buffer flushing; for example, with +.IR "\fIfflush\fR\^(\|)". +.P +A stream opened by +\fIpopen\fR() +should be closed by +\fIpclose\fR(). +.P +The behavior of +\fIpopen\fR() +is specified for values of +.IR mode +of +.IR r +and +.IR w . +Other modes such as +.IR rb +and +.IR wb +might be supported by specific implementations, but these would not be +portable features. Note that historical implementations of +\fIpopen\fR() +only check to see if the first character of +.IR mode +is +.IR r . +Thus, a +.IR mode +of +.IR "robert the robot" +would be treated as +.IR mode +.IR r , +and a +.IR mode +of +.IR "anything else" +would be treated as +.IR mode +.IR w . +.P +If the application calls +\fIwaitpid\fR() +or +\fIwaitid\fR() +with a +.IR pid +argument greater than 0, and it still has a stream that was called with +\fIpopen\fR() +open, it must ensure that +.IR pid +does not refer to the process started by +\fIpopen\fR(). +.P +To determine whether or not the environment specified in the Shell and Utilities volume of POSIX.1\(hy2017 is +present, use the function call: +.sp +.RS 4 +.nf + +sysconf(_SC_2_VERSION) +.fi +.P +.RE +.P +(See +.IR "\fIsysconf\fR\^(\|)"). +.SH RATIONALE +The +\fIpopen\fR() +function should not be used by programs that have set user (or group) +ID privileges. The +\fIfork\fR() +and +.IR exec +family of functions (except +\fIexeclp\fR() +and +\fIexecvp\fR()), +should be used instead. This prevents any unforeseen manipulation of +the environment of the user that could cause execution of commands not +anticipated by the calling program. +.P +If the original and +\fIpopen\fR()ed +processes both intend to read or write or read and write a common file, +and either will be using FILE-type C functions (\c +\fIfread\fR(), +\fIfwrite\fR(), +and so on), the rules for sharing file handles must be observed (see +.IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams"). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfork\fR\^(\|)", +.IR "\fIpclose\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIsh\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_fadvise.3p b/upstream/archlinux/man3p/posix_fadvise.3p new file mode 100644 index 00000000..850c0b23 --- /dev/null +++ b/upstream/archlinux/man3p/posix_fadvise.3p @@ -0,0 +1,135 @@ +'\" et +.TH POSIX_FADVISE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_fadvise +\(em file advisory information +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_fadvise(int \fIfd\fP, off_t \fIoffset\fP, off_t \fIlen\fP, int \fIadvice\fP); +.fi +.SH DESCRIPTION +The +\fIposix_fadvise\fR() +function shall advise the implementation on the expected behavior +of the application with respect to the data in the file associated with +the open file descriptor, +.IR fd , +starting at +.IR offset +and continuing for +.IR len +bytes. The specified range need not currently exist in the file. If +.IR len +is zero, all data following +.IR offset +is specified. The implementation may use this information to optimize +handling of the specified data. The +\fIposix_fadvise\fR() +function shall have no effect on the semantics of other operations on +the specified data, although it may affect the performance of other +operations. +.P +The advice to be applied to the data is specified by the +.IR advice +parameter and may be one of the following values: +.IP POSIX_FADV_NORMAL 6 +.br +Specifies that the application has no advice to give on its behavior +with respect to the specified data. It is the default characteristic if +no advice is given for an open file. +.IP POSIX_FADV_SEQUENTIAL 6 +.br +Specifies that the application expects to access the specified data +sequentially from lower offsets to higher offsets. +.IP POSIX_FADV_RANDOM 6 +.br +Specifies that the application expects to access the specified data in +a random order. +.IP POSIX_FADV_WILLNEED 6 +.br +Specifies that the application expects to access the specified data in +the near future. +.IP POSIX_FADV_DONTNEED 6 +.br +Specifies that the application expects that it will not access the +specified data in the near future. +.IP POSIX_FADV_NOREUSE 6 +.br +Specifies that the application expects to access the specified data +once and then not reuse it thereafter. +.P +These values are defined in +.IR . +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_fadvise\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_fadvise\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor. +.TP +.BR EINVAL +The value of +.IR advice +is invalid, or the value of +.IR len +is less than zero. +.TP +.BR ESPIPE +The +.IR fd +argument is associated with a pipe or FIFO. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_fadvise\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIposix_madvise\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_fallocate.3p b/upstream/archlinux/man3p/posix_fallocate.3p new file mode 100644 index 00000000..d0a684bf --- /dev/null +++ b/upstream/archlinux/man3p/posix_fallocate.3p @@ -0,0 +1,162 @@ +'\" et +.TH POSIX_FALLOCATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_fallocate +\(em file space control +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_fallocate(int \fIfd\fP, off_t \fIoffset\fP, off_t \fIlen\fP); +.fi +.SH DESCRIPTION +The +\fIposix_fallocate\fR() +function shall ensure that any required storage for regular file data +starting at +.IR offset +and continuing for +.IR len +bytes is allocated on the file system storage media. If +\fIposix_fallocate\fR() +returns successfully, subsequent writes to the specified file data +shall not fail due to the lack of free space on the file system storage +media. +.P +If the +.IR offset +\c +.IR len +is beyond the current file size, then +\fIposix_fallocate\fR() +shall adjust the file size to +.IR offset +\c +.IR len . +Otherwise, the file size shall not be changed. +.P +It is implementation-defined whether a previous +\fIposix_fadvise\fR() +call influences allocation strategy. +.P +Space allocated via +\fIposix_fallocate\fR() +shall be freed by a successful call to +\fIcreat\fR() +or +\fIopen\fR() +that truncates the size of the file. Space allocated via +\fIposix_fallocate\fR() +may be freed by a successful call to +\fIftruncate\fR() +that reduces the file size to a size smaller than +.IR offset +\c +.IR len . +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_fallocate\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_fallocate\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fd +argument is not a valid file descriptor. +.TP +.BR EBADF +The +.IR fd +argument references a file that was opened without write permission. +.TP +.BR EFBIG +The value of +.IR offset +\c +.IR len +is greater than the maximum file size. +.TP +.BR EINTR +A signal was caught during execution. +.TP +.BR EINVAL +The +.IR len +argument is less than zero, or the +.IR offset +argument is less than zero, or the underlying file system does not +support this operation. +.TP +.BR EIO +An I/O error occurred while reading from or writing to a file system. +.TP +.BR ENODEV +The +.IR fd +argument does not refer to a regular file. +.TP +.BR ENOSPC +There is insufficient free space remaining on the file system storage +media. +.TP +.BR ESPIPE +The +.IR fd +argument is associated with a pipe or FIFO. +.P +The +\fIposix_fallocate\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR len +argument is zero. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_fallocate\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcreat\fR\^(\|)", +.IR "\fIftruncate\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_madvise.3p b/upstream/archlinux/man3p/posix_madvise.3p new file mode 100644 index 00000000..b016547e --- /dev/null +++ b/upstream/archlinux/man3p/posix_madvise.3p @@ -0,0 +1,146 @@ +'\" et +.TH POSIX_MADVISE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_madvise +\(em memory advisory information and alignment control +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_madvise(void *\fIaddr\fP, size_t \fIlen\fP, int \fIadvice\fP); +.fi +.SH DESCRIPTION +The +\fIposix_madvise\fR() +function shall advise the implementation on the expected behavior of +the application with respect to the data in the memory starting at +address +.IR addr , +and continuing for +.IR len +bytes. The implementation may use this information to optimize handling +of the specified data. The +\fIposix_madvise\fR() +function shall have no effect on the semantics of access to memory in +the specified range, although it may affect the performance of access. +.P +The implementation may require that +.IR addr +be a multiple of the page size, which is the value returned by +\fIsysconf\fR() +when the name value _SC_PAGESIZE is used. +.P +The advice to be applied to the memory range is specified by the +.IR advice +parameter and may be one of the following values: +.IP POSIX_MADV_NORMAL 6 +.br +Specifies that the application has no advice to give on its behavior +with respect to the specified range. It is the default characteristic +if no advice is given for a range of memory. +.IP POSIX_MADV_SEQUENTIAL 6 +.br +Specifies that the application expects to access the specified range +sequentially from lower addresses to higher addresses. +.IP POSIX_MADV_RANDOM 6 +.br +Specifies that the application expects to access the specified range in +a random order. +.IP POSIX_MADV_WILLNEED 6 +.br +Specifies that the application expects to access the specified range in +the near future. +.IP POSIX_MADV_DONTNEED 6 +.br +Specifies that the application expects that it will not access the +specified range in the near future. +.P +These values are defined in the +.IR +header. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_madvise\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_madvise\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR advice +is invalid. +.TP +.BR ENOMEM +Addresses in the range starting at +.IR addr +and continuing for +.IR len +bytes are partly or completely outside the range allowed for the +address space of the calling process. +.br +.P +The +\fIposix_madvise\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR addr +is not a multiple of the value returned by +\fIsysconf\fR() +when the name value _SC_PAGESIZE is used. +.TP +.BR EINVAL +The value of +.IR len +is zero. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_madvise\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_fadvise\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_mem_offset.3p b/upstream/archlinux/man3p/posix_mem_offset.3p new file mode 100644 index 00000000..ba0b406e --- /dev/null +++ b/upstream/archlinux/man3p/posix_mem_offset.3p @@ -0,0 +1,127 @@ +'\" et +.TH POSIX_MEM_OFFSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_mem_offset +\(em find offset and length of a mapped typed memory block +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_mem_offset(const void *restrict \fIaddr\fP, size_t \fIlen\fP, + off_t *restrict \fIoff\fP, size_t *restrict \fIcontig_len\fP, + int *restrict \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIposix_mem_offset\fR() +function shall return in the variable pointed to by +.IR off +a value that identifies the offset (or location), within a memory +object, of the memory block currently mapped at +.IR addr . +The function shall return in the variable pointed to by +.IR fildes , +the descriptor used (via +\fImmap\fR()) +to establish the mapping which contains +.IR addr . +If that descriptor was closed since the mapping was established, the +returned value of +.IR fildes +shall be \-1. The +.IR len +argument specifies the length of the block of the memory object the +user wishes the offset for; upon return, the value pointed to by +.IR contig_len +shall equal either +.IR len , +or the length of the largest contiguous block of the memory object that +is currently mapped to the calling process starting at +.IR addr , +whichever is smaller. +.P +If the memory object mapped at +.IR addr +is a typed memory object, then if the +.IR off +and +.IR contig_len +values obtained by calling +\fIposix_mem_offset\fR() +are used in a call to +\fImmap\fR() +with a file descriptor that refers to the same memory pool as +.IR fildes +(either through the same port or through a different port), and that +was opened with neither the POSIX_TYPED_MEM_ALLOCATE nor the +POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, +the typed memory area that is mapped shall be exactly the same area +that was mapped at +.IR addr +in the address space of the process that called +\fIposix_mem_offset\fR(). +.P +If the memory object specified by +.IR fildes +is not a typed memory object, then the behavior of this function is +implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_mem_offset\fR() +function shall return zero; otherwise, the corresponding error status +value shall be returned. +.SH ERRORS +The +\fIposix_mem_offset\fR() +function shall fail if: +.TP +.BR EACCES +The process has not mapped a memory object supported by this function +at the given address +.IR addr . +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_memalign.3p b/upstream/archlinux/man3p/posix_memalign.3p new file mode 100644 index 00000000..f822ae69 --- /dev/null +++ b/upstream/archlinux/man3p/posix_memalign.3p @@ -0,0 +1,149 @@ +'\" et +.TH POSIX_MEMALIGN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_memalign +\(em aligned memory allocation +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_memalign(void **\fImemptr\fP, size_t \fIalignment\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIposix_memalign\fR() +function shall allocate +.IR size +bytes aligned on a boundary specified by +.IR alignment , +and shall return a pointer to the allocated memory in +.IR memptr . +The value of +.IR alignment +shall be a power of two multiple of +.IR sizeof (\c +.BR "void *" ). +.P +Upon successful completion, the value pointed to by +.IR memptr +shall be a multiple of +.IR alignment . +.P +If the size of the space requested is 0, the behavior is +implementation-defined: either a null pointer shall be returned in +.IR memptr , +or the behavior shall be as if the size were some non-zero value, +except that the behavior is undefined if the the value returned in +.IR memptr +is used to access an object. +.P +The +\fIfree\fR() +function shall deallocate memory that has previously been allocated by +\fIposix_memalign\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_memalign\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error and the contents of +.IR memptr +shall either be left unmodified or be set to a null pointer. +.P +If +.IR size +is 0, either: +.IP " *" 4 +\fIposix_memalign\fR() +shall not attempt to allocate any space, in which case either an +implementation-defined error number shall be returned, or zero shall +be returned with a null pointer returned in +.IR memptr , +or +.IP " *" 4 +\fIposix_memalign\fR() +shall attempt to allocate some space and, if the allocation succeeds, +zero shall be returned and a pointer to the allocated space shall be +returned in +.IR memptr . +The application shall ensure that the pointer is not used to access +an object. +.SH ERRORS +The +\fIposix_memalign\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the alignment parameter is not a power of two multiple of +.IR sizeof (\c +.BR "void *" ). +.TP +.BR ENOMEM +There is insufficient memory available with the requested alignment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example shows how applications can obtain consistent +behavior on error by setting *\c +.IR memptr +to be a null pointer before calling +\fIposix_memalign\fR(). +.sp +.RS 4 +.nf + +void *ptr = NULL; +\&... +//do some work, which might goto error +if (posix_memalign(&ptr, align, size)) + goto error; +.P +//do some more work, which might goto error +\&... +error: + free(ptr); + //more cleanup; +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIposix_memalign\fR() +function is part of the Advisory Information option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_openpt.3p b/upstream/archlinux/man3p/posix_openpt.3p new file mode 100644 index 00000000..cf5dd29a --- /dev/null +++ b/upstream/archlinux/man3p/posix_openpt.3p @@ -0,0 +1,177 @@ +'\" et +.TH POSIX_OPENPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_openpt +\(em open a pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_openpt(int \fIoflag\fP); +.fi +.SH DESCRIPTION +The +\fIposix_openpt\fR() +function shall establish a connection between a master device for a +pseudo-terminal and a file descriptor. The file descriptor shall be +allocated as described in +.IR "Section 2.14" ", " "File Descriptor Allocation" +and can be used by other I/O functions that refer to that pseudo-terminal. +.P +The file status flags and file access modes of the open file +description shall be set according to the value of +.IR oflag . +.P +Values for +.IR oflag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP O_RDWR 12 +Open for reading and writing. +.IP O_NOCTTY 12 +If set +\fIposix_openpt\fR() +shall not cause the terminal device to become the controlling terminal +for the process. +.P +The behavior of other values for the +.IR oflag +argument is unspecified. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_openpt\fR() +function shall open a file descriptor for a master pseudo-terminal +device and return a non-negative integer representing the file +descriptor. Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIposix_openpt\fR() +function shall fail if: +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.P +The +\fIposix_openpt\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR oflag +is not valid. +.TP +.BR EAGAIN +Out of pseudo-terminal resources. +.TP +.BR ENOSR +Out of STREAMS resources. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Opening a Pseudo-Terminal and Returning the Name of the Slave Device and a File Descriptor" +.sp +.RS 4 +.nf + +#include +#include +.P +int masterfd, slavefd; +char *slavedevice; +.P +masterfd = posix_openpt(O_RDWR|O_NOCTTY); +.P +if (masterfd == -1 + || grantpt (masterfd) == -1 + || unlockpt (masterfd) == -1 + || (slavedevice = ptsname (masterfd)) == NULL) + return -1; +.P +printf("slave device is: %s\en", slavedevice); +.P +slavefd = open(slavedevice, O_RDWR|O_NOCTTY); +if (slavefd < 0) + return -1; +.fi +.P +.RE +.SH "APPLICATION USAGE" +This function is a method for portably obtaining a file descriptor of a +master terminal device for a pseudo-terminal. The +\fIgrantpt\fR() +and +\fIptsname\fR() +functions can be used to manipulate mode and ownership permissions, and +to obtain the name of the slave device, respectively. +.SH RATIONALE +The standard developers considered the matter of adding a special +device for cloning master pseudo-terminals: the +.BR /dev/ptmx +device. However, consensus could not be reached, and it was felt that +adding a new function would permit other implementations. The +\fIposix_openpt\fR() +function is designed to complement the +\fIgrantpt\fR(), +\fIptsname\fR(), +and +\fIunlockpt\fR() +functions. +.P +On implementations supporting the +.BR /dev/ptmx +clone device, opening the master device of a pseudo-terminal is simply: +.sp +.RS 4 +.nf + +mfdp = open("/dev/ptmx", oflag ); +if (mfdp < 0) + return -1; +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "File Descriptor Allocation", +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawn.3p b/upstream/archlinux/man3p/posix_spawn.3p new file mode 100644 index 00000000..876fa9d1 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawn.3p @@ -0,0 +1,936 @@ +'\" et +.TH POSIX_SPAWN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawn, +posix_spawnp +\(em spawn a process +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn(pid_t *restrict \fIpid\fP, const char *restrict \fIpath\fP, + const posix_spawn_file_actions_t *\fIfile_actions\fP, + const posix_spawnattr_t *restrict \fIattrp\fP, + char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]); +int posix_spawnp(pid_t *restrict \fIpid\fP, const char *restrict \fIfile\fP, + const posix_spawn_file_actions_t *\fIfile_actions\fP, + const posix_spawnattr_t *restrict \fIattrp\fP, + char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]); +.fi +.SH DESCRIPTION +The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions shall create a new process (child process) from the specified +process image. The new process image shall be constructed from a regular +executable file called the new process image file. +.P +When a C program is executed as the result of this call, it shall be +entered as a C-language function call as follows: +.sp +.RS 4 +.nf + +int main(int \fIargc\fP, char *\fIargv\fP[]); +.fi +.P +.RE +.P +where +.IR argc +is the argument count and +.IR argv +is an array of character pointers to the arguments themselves. In +addition, the following variable: +.sp +.RS 4 +.nf + +extern char **environ; +.fi +.P +.RE +.P +shall be initialized as a pointer to an array of character pointers to +the environment strings. +.P +The argument +.IR argv +is an array of character pointers to null-terminated strings. The last +member of this array shall be a null pointer and is not +counted in +.IR argc . +These strings constitute the argument list available to the new process +image. The value in +.IR argv [0] +should point to a filename string that is associated with the process +image being started by the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +function. +.P +The argument +.IR envp +is an array of character pointers to null-terminated strings. These +strings constitute the environment for the new process image. The +environment array is terminated by a null pointer. +.P +The number of bytes available for the combined argument +and environment lists of the child process is +{ARG_MAX}. +The implementation shall specify in the system documentation (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 2" ", " "Conformance") +whether any list overhead, such as length words, null +terminators, pointers, or alignment bytes, is included in this total. +.P +The +.IR path +argument to +\fIposix_spawn\fR() +is a pathname that identifies the new process image file to execute. +.P +The +.IR file +parameter to +\fIposix_spawnp\fR() +shall be used to construct a pathname that identifies the new process +image file. If the +.IR file +parameter contains a + +character, the +.IR file +parameter shall be used as the pathname for the new process image +file. Otherwise, the path prefix for this file shall be obtained by a +search of the directories passed as the environment variable +.IR PATH +(see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables"). +If this environment variable is not defined, the results of the search +are implementation-defined. +.P +If +.IR file_actions +is a null pointer, then file descriptors open in the calling process +shall remain open in the child process, except for those whose +close-on-\c +.IR exec +flag FD_CLOEXEC is set (see +.IR "\fIfcntl\fR\^(\|)"). +For those file descriptors that remain open, the child process shall +not inherit any file locks, but all remaining attributes of the +corresponding open file descriptions (see +.IR "\fIfcntl\fR\^(\|)"), +shall remain unchanged. +.P +If +.IR file_actions +is not NULL, then the file descriptors open in the child process shall +be those open in the calling process as modified by the spawn file +actions object pointed to by +.IR file_actions +and the FD_CLOEXEC flag of each remaining open file descriptor after +the spawn file actions have been processed. The effective order of +processing the spawn file actions shall be: +.IP " 1." 4 +The set of open file descriptors for the child process shall initially +be the same set as is open for the calling process. The child process +shall not inherit any file locks, but all remaining attributes of the +corresponding open file descriptions (see +.IR "\fIfcntl\fR\^(\|)"), +shall remain unchanged. +.IP " 2." 4 +The signal mask, signal default actions, and the effective user and +group IDs for the child process shall be changed as specified in the +attributes object referenced by +.IR attrp . +.IP " 3." 4 +The file actions specified by the spawn file actions object shall be +performed in the order in which they were added to the spawn file +actions object. +.IP " 4." 4 +Any file descriptor that has its FD_CLOEXEC flag set (see +.IR "\fIfcntl\fR\^(\|)") +shall be closed. +.P +If file descriptor 0, 1, or 2 would otherwise be closed in the new +process image created by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(), +implementations may open an unspecified file for the file descriptor in +the new process image. If a standard utility or a conforming application +is executed with file descriptor 0 not open for reading or with file +descriptor 1 or 2 not open for writing, the environment in which the +utility or application is executed shall be deemed non-conforming, and +consequently the utility or application might not behave as described +in this standard. +.P +The +.BR posix_spawnattr_t +spawn attributes object type is defined in +.IR . +It shall contain at least the attributes defined below. +.P +If the POSIX_SPAWN_SETPGROUP flag is set in the +.IR spawn-flags +attribute +of the object referenced by +.IR attrp , +and the +.IR spawn-pgroup +attribute of the same object is non-zero, then the child's process +group shall be as specified in the +.IR spawn-pgroup +attribute of the object referenced by +.IR attrp . +.P +As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +and the +.IR spawn-pgroup +attribute of the same object is set to zero, then the child shall be in +a new process group with a process group ID equal to its process ID. +.P +If the POSIX_SPAWN_SETPGROUP flag is not set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +the new child process shall inherit the parent's process group. +.P +If the POSIX_SPAWN_SETSCHEDPARAM flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +but POSIX_SPAWN_SETSCHEDULER is not set, the new process image shall +initially have the scheduling policy of the calling process with the +scheduling parameters specified in the +.IR spawn-schedparam +attribute of the object referenced by +.IR attrp . +.P +If the POSIX_SPAWN_SETSCHEDULER flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +(regardless of the setting of the POSIX_SPAWN_SETSCHEDPARAM flag), the +new process image shall initially have the scheduling policy specified +in the +.IR spawn-schedpolicy +attribute of the object referenced by +.IR attrp +and the scheduling parameters specified in the +.IR spawn-schedparam +attribute of the same object. +.P +The POSIX_SPAWN_RESETIDS flag in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +governs the effective user ID of the child process. If this flag is +not set, the child process shall inherit the effective user ID of the +parent process. If this flag is set, the effective user ID of the child +process shall be reset to the parent's real user ID. In either case, +if the set-user-ID mode bit of the new process image file is set, the +effective user ID of the child process shall become that file's owner +ID before the new process image begins execution. +.P +The POSIX_SPAWN_RESETIDS flag in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +also governs the effective group ID of the child process. If this flag +is not set, the child process shall inherit the effective group ID of the +parent process. If this flag is set, the effective group ID of the child +process shall be reset to the parent's real group ID. In either case, +if the set-group-ID mode bit of the new process image file is set, the +effective group ID of the child process shall become that file's group +ID before the new process image begins execution. +.P +If the POSIX_SPAWN_SETSIGMASK flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +the child process shall initially have the signal mask specified in the +.IR spawn-sigmask +attribute of the object referenced by +.IR attrp . +.P +If the POSIX_SPAWN_SETSIGDEF flag is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +the signals specified in the +.IR spawn-sigdefault +attribute of the same object shall be set to their default actions in +the child process. Signals set to the default action in the parent +process shall be set to the default action in the child process. +.P +Signals set to be caught by the calling process shall be set to the +default action in the child process. +.P +Except for SIGCHLD, signals set to be ignored by the calling process +image shall be set to be ignored by the child process, unless otherwise +specified by the POSIX_SPAWN_SETSIGDEF flag being set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp +and the signals being indicated in the +.IR spawn-sigdefault +attribute of the object referenced by +.IR attrp . +.P +If the SIGCHLD signal is set to be ignored by the calling process, it +is unspecified whether the SIGCHLD signal is set to be ignored or to +the default action in the child process, unless otherwise specified by +the POSIX_SPAWN_SETSIGDEF flag being set in the +.IR spawn_flags +attribute of the object referenced by +.IR attrp +and the SIGCHLD signal being indicated in the +.IR spawn_sigdefault +attribute of the object referenced by +.IR attrp . +.P +If the value of the +.IR attrp +pointer is NULL, then the default values are used. +.P +All process attributes, other than those influenced by the attributes +set in the object referenced by +.IR attrp +as specified above or by the file descriptor manipulations specified in +.IR file_actions , +shall appear in the new process image as though +\fIfork\fR() +had been called to create a child process and then a member of the +.IR exec +family of functions had been called by the child process to execute the +new process image. +.P +It is implementation-defined whether the fork handlers are run when +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +is called. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +shall return the process ID of the child process to the parent process, +in the variable pointed to by a non-NULL +.IR pid +argument, and shall return zero as the function return value. +Otherwise, no child process shall be created, the value stored into the +variable pointed to by a non-NULL +.IR pid +is unspecified, and an error number shall be returned as the function +return value to indicate the error. If the +.IR pid +argument is a null pointer, the process ID of the child is not returned +to the caller. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +or +.IR attrp +is invalid. +.P +If this error occurs after the calling process successfully returns +from the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +function, the child process may exit with exit status 127. +.P +If +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fail for any of the reasons that would cause +\fIfork\fR() +or one of the +.IR exec +family of functions to fail, an error value shall be returned as +described by +\fIfork\fR() +and +.IR exec , +respectively (or, if the error occurs after the calling process +successfully returns, the child process shall exit with exit status 127). +.P +If POSIX_SPAWN_SETPGROUP is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +and +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails while changing the child's process group, an error value shall be +returned as described by +\fIsetpgid\fR() +(or, if the error occurs after the calling process successfully +returns, the child process shall exit with exit status 127). +.P +If POSIX_SPAWN_SETSCHEDPARAM is set and POSIX_SPAWN_SETSCHEDULER is not +set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +then if +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails for any of the reasons that would cause +\fIsched_setparam\fR() +to fail, an error value shall be returned as described by +\fIsched_setparam\fR() +(or, if the error occurs after the calling process successfully +returns, the child process shall exit with exit status 127). +.P +If POSIX_SPAWN_SETSCHEDULER is set in the +.IR spawn-flags +attribute of the object referenced by +.IR attrp , +and if +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails for any of the reasons that would cause +\fIsched_setscheduler\fR() +to fail, an error value shall be returned as described by +\fIsched_setscheduler\fR() +(or, if the error occurs after the calling process successfully +returns, the child process shall exit with exit status 127). +.P +If the +.IR file_actions +argument is not NULL, and specifies any +.IR close , +.IR dup2 , +or +.IR open +actions to be performed, and if +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +fails for any of the reasons that would cause +\fIclose\fR(), +\fIdup2\fR(), +or +\fIopen\fR() +to fail, an error value shall be returned as described by +\fIclose\fR(), +\fIdup2\fR(), +and +\fIopen\fR(), +respectively (or, if the error occurs after the calling process +successfully returns, the child process shall exit with exit status +127). An open file action may, by itself, result in any of the errors +described by +\fIclose\fR() +or +\fIdup2\fR(), +in addition to those described by +\fIopen\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.P +See also the APPLICATION USAGE section for +.IR "\fIexec\fR\^". +.SH RATIONALE +The +\fIposix_spawn\fR() +function and its close relation +\fIposix_spawnp\fR() +have been introduced to overcome the following perceived difficulties +with +\fIfork\fR(): +the +\fIfork\fR() +function is difficult or impossible to implement without swapping or +dynamic address translation. +.IP " *" 4 +Swapping is generally too slow for a realtime environment. +.IP " *" 4 +Dynamic address translation is not available everywhere that POSIX +might be useful. +.IP " *" 4 +Processes are too useful to simply option out of POSIX whenever it must +run without address translation or other MMU services. +.P +Thus, POSIX needs process creation and file execution primitives that +can be efficiently implemented without address translation or other MMU +services. +.P +The +\fIposix_spawn\fR() +function is implementable as a library routine, but both +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are designed as kernel operations. Also, although they may be an +efficient replacement for many +\fIfork\fR()/\c +.IR exec +pairs, their goal is to provide useful process creation primitives for +systems that have difficulty with +\fIfork\fR(), +not to provide drop-in replacements for +\fIfork\fR()/\c +.IR exec . +.P +This view of the role of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +influenced the design of their API. It does not attempt to provide the +full functionality of +\fIfork\fR()/\c +.IR exec +in which arbitrary user-specified operations of any sort are permitted +between the creation of the child process and the execution of the new +process image; any attempt to reach that level would need to provide a +programming language as parameters. Instead, +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are process creation primitives like the +.IR Start_Process +and +.IR Start_Process_Search +Ada language bindings package +.IR POSIX_Process_Primitives +and also like those in many operating systems that are not UNIX +systems, but with some POSIX-specific additions. +.P +To achieve its coverage goals, +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +have control of six types of inheritance: file descriptors, process +group ID, user and group ID, signal mask, scheduling, and whether each +signal ignored in the parent will remain ignored in the child, or be +reset to its default action in the child. +.P +Control of file descriptors is required to allow an independently +written child process image to access data streams opened by and even +generated or read by the parent process without being specifically +coded to know which parent files and file descriptors are to be used. +Control of the process group ID is required to control how the +job control of the child process relates to that of the parent. +.P +Control of the signal mask and signal defaulting is sufficient to +support the implementation of +\fIsystem\fR(). +Although support for +\fIsystem\fR() +is not explicitly one of the goals for +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(), +it is covered under the ``at least 50%'' coverage goal. +.P +The intention is that the normal file descriptor inheritance across +\fIfork\fR(), +the subsequent effect of the specified spawn file actions, and the +normal file descriptor inheritance across one of the +.IR exec +family of functions should fully specify open file inheritance. The +implementation need make no decisions regarding the set of open file +descriptors when the child process image begins execution, those +decisions having already been made by the caller and expressed as the +set of open file descriptors and their FD_CLOEXEC flags at the time of +the call and the spawn file actions object specified in the call. We +have been assured that in cases where the POSIX +.IR Start_Process +Ada primitives have been implemented in a library, this method of +controlling file descriptor inheritance may be implemented very easily. +.P +We can identify several problems with +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(), +but there does not appear to be a solution that introduces fewer +problems. Environment modification for child process attributes not +specifiable via the +.IR attrp +or +.IR file_actions +arguments must be done in the parent process, and since the parent +generally wants to save its context, it is more costly than similar +functionality with +\fIfork\fR()/\c +.IR exec . +It is also complicated to modify the environment of a multi-threaded +process temporarily, since all threads must agree when it is safe for +the environment to be changed. However, this cost is only borne by +those invocations of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +that use the additional functionality. Since extensive modifications +are not the usual case, and are particularly unlikely in time-critical +code, keeping much of the environment control out of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +is appropriate design. +.P +The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions do not have all the power of +\fIfork\fR()/\c +.IR exec . +This is to be expected. The +\fIfork\fR() +function is a wonderfully powerful operation. We do not expect to +duplicate its functionality in a simple, fast function with no special +hardware requirements. It is worth noting that +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are very similar to the process creation operations on many operating +systems that are not UNIX systems. +.SS "Requirements" +.P +The requirements for +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +are: +.IP " *" 4 +They must be implementable without an MMU or unusual hardware. +.IP " *" 4 +They must be compatible with existing POSIX standards. +.P +Additional goals are: +.IP " *" 4 +They should be efficiently implementable. +.IP " *" 4 +They should be able to replace at least 50% of typical executions of +\fIfork\fR(). +.IP " *" 4 +A system with +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +and without +\fIfork\fR() +should be useful, at least for realtime applications. +.IP " *" 4 +A system with +\fIfork\fR() +and the +.IR exec +family should be able to implement +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +as library routines. +.SS "Two-Syntax" +.P +POSIX +.IR exec +has several calling sequences with approximately the same +functionality. These appear to be required for compatibility with +existing practice. Since the existing practice for the +.IR posix_spawn* (\|) +functions is otherwise substantially unlike POSIX, we feel that +simplicity outweighs compatibility. There are, therefore, only two +names for the +.IR posix_spawn* (\|) +functions. +.P +The parameter list does not differ between +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(); +\fIposix_spawnp\fR() +interprets the second parameter more elaborately than +\fIposix_spawn\fR(). +.SS "Compatibility with POSIX.5 (Ada)" +.P +The +.IR Start_Process +and +.IR Start_Process_Search +procedures from the +.IR POSIX_Process_Primitives +package from the Ada language binding to POSIX.1 encapsulate +\fIfork\fR() +and +.IR exec +functionality in a manner similar to that of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR(). +Originally, in keeping with our simplicity goal, the standard +developers had limited the capabilities of +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +to a subset of the capabilities of +.IR Start_Process +and +.IR Start_Process_Search ; +certain non-default capabilities were not supported. However, based on +suggestions by the ballot group to improve file descriptor mapping or +drop it, and on the advice of an Ada Language Bindings working group +member, the standard developers decided that +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +should be sufficiently powerful to implement +.IR Start_Process +and +.IR Start_Process_Search . +The rationale is that if the Ada language binding to such a primitive +had already been approved as an IEEE standard, there can be little +justification for not approving the functionally-equivalent parts of a +C binding. The only three capabilities provided by +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +that are not provided by +.IR Start_Process +and +.IR Start_Process_Search +are optionally specifying the child's process group ID, the set of +signals to be reset to default signal handling in the child process, +and the child's scheduling policy and parameters. +.P +For the Ada language binding for +.IR Start_Process +to be implemented with +\fIposix_spawn\fR(), +that binding would need to explicitly pass an empty signal mask and the +parent's environment to +\fIposix_spawn\fR() +whenever the caller of +.IR Start_Process +allowed these arguments to default, since +\fIposix_spawn\fR() +does not provide such defaults. The ability of +.IR Start_Process +to mask user-specified signals during its execution is functionally +unique to the Ada language binding and must be dealt with in the +binding separately from the call to +\fIposix_spawn\fR(). +.SS "Process Group" +.P +The process group inheritance field can be used to join the child +process with an existing process group. By assigning a value of zero to +the +.IR spawn-pgroup +attribute of the object referenced by +.IR attrp , +the +\fIsetpgid\fR() +mechanism will place the child process in a new process group. +.SS "Threads" +.P +Without the +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions, systems without address translation can still use threads to +give an abstraction of concurrency. In many cases, thread creation +suffices, but it is not always a good substitute. The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions are considerably ``heavier'' than thread creation. Processes +have several important attributes that threads do not. Even without +address translation, a process may have base-and-bound memory +protection. Each process has a process environment including security +attributes and file capabilities, and powerful scheduling attributes. +Processes abstract the behavior of non-uniform-memory-architecture +multi-processors better than threads, and they are more convenient to +use for activities that are not closely linked. +.P +The +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +functions may not bring support for multiple processes to every +configuration. Process creation is not the only piece of operating +system support required to support multiple processes. The total cost +of support for multiple processes may be quite high in some +circumstances. Existing practice shows that support for multiple +processes is uncommon and threads are common among ``tiny kernels''. +There should, therefore, probably continue to be AEPs for operating +systems with only one process. +.SS "Asynchronous Error Notification" +.P +A library implementation of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +may not be able to detect all possible errors before it forks the child +process. POSIX.1\(hy2008 provides for an error indication returned from a child +process which could not successfully complete the spawn operation via a +special exit status which may be detected using the status value +returned by +\fIwait\fR(), +\fIwaitid\fR(), +and +\fIwaitpid\fR(). +.P +The +.IR stat_val +interface and the macros used to interpret it are not well suited to +the purpose of returning API errors, but they are the only path +available to a library implementation. Thus, an implementation may +cause the child process to exit with exit status 127 for any error +detected during the spawn process after the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +function has successfully returned. +.P +The standard developers had proposed using two additional macros to +interpret +.IR stat_val . +The first, WIFSPAWNFAIL, would have detected a status that indicated +that the child exited because of an error detected during the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operations rather than during actual execution of the child process +image; the second, WSPAWNERRNO, would have extracted the error value if +WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group +strongly opposed this because it would make a library implementation of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +dependent on kernel modifications to +\fIwaitpid\fR() +to be able to embed special information in +.IR stat_val +to indicate a spawn failure. +.P +The 8 bits of child process exit status that are guaranteed by POSIX.1\(hy2008 to +be accessible to the waiting parent process are insufficient to +disambiguate a spawn error from any other kind of error that may be +returned by an arbitrary process image. No other bits of the exit +status are required to be visible in +.IR stat_val , +so these macros could not be strictly implemented at the library level. +Reserving an exit status of 127 for such spawn errors is consistent +with the use of this value by +\fIsystem\fR() +and +\fIpopen\fR() +to signal failures in these operations that occur after the function +has returned but before a shell is able to execute. The exit status of +127 does not uniquely identify this class of error, nor does it provide +any detailed information on the nature of the failure. Note that a +kernel implementation of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +is permitted (and encouraged) to return any possible error as the +function value, thus providing more detailed failure information to the +parent process. +.P +Thus, no special macros are available to isolate asynchronous +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +errors. Instead, errors detected by the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operations in the context of the child process before the new process +image executes are reported by setting the child's exit status to 127. +The calling process may use the WIFEXITED and WEXITSTATUS macros on the +.IR stat_val +stored by the +\fIwait\fR() +or +\fIwaitpid\fR() +functions to detect spawn failures to the extent that other status +values with which the child process image may exit (before the parent +can conclusively determine that the child process image has begun +execution) are distinct from exit status 127. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIalarm\fR\^(\|)", +.IR "\fIchmod\fR\^(\|)", +.IR "\fIclose\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_adddup2\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawn_file_actions_addclose.3p b/upstream/archlinux/man3p/posix_spawn_file_actions_addclose.3p new file mode 100644 index 00000000..52369993 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawn_file_actions_addclose.3p @@ -0,0 +1,330 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawn_file_actions_addclose, +posix_spawn_file_actions_addopen +\(em add close or open action to spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t + *\fIfile_actions\fP, int \fIfildes\fP); +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t + *restrict \fIfile_actions\fP, int \fIfildes\fP, + const char *restrict \fIpath\fP, int \fIoflag\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +These functions shall add or delete a close or open action to a +spawn file actions object. +.P +A spawn file actions object is of type +.BR posix_spawn_file_actions_t +(defined in +.IR ) +and is used to specify a series of actions to be performed by a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operation in order to arrive at the set of open file descriptors for +the child process given the set of open file descriptors of the parent. +POSIX.1\(hy2008 does not define comparison or assignment operators for the type +.BR posix_spawn_file_actions_t . +.P +A spawn file actions object, when passed to +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(), +shall specify how the set of open file descriptors in the calling +process is transformed into a set of potentially open file descriptors +for the spawned process. This transformation shall be as if the +specified sequence of actions was performed exactly once, in the +context of the spawned process (prior to execution of the new process +image), in the order in which the actions were added to the object; +additionally, when the new process image is executed, any file +descriptor (from this new set) which has its FD_CLOEXEC +flag set shall be closed (see +.IR "\fIposix_spawn\fR\^(\|)"). +.P +The +\fIposix_spawn_file_actions_addclose\fR() +function shall add a +.IR close +action to the object referenced by +.IR file_actions +that shall cause the file descriptor +.IR fildes +to be closed (as if +.IR close (\c +.IR fildes ) +had been called) when a new process is spawned using this file actions +object. +.P +The +\fIposix_spawn_file_actions_addopen\fR() +function shall add an +.IR open +action to the object referenced by +.IR file_actions +that shall cause the file named by +.IR path +to be opened (as if +.IR open (\c +.IR path , +.IR oflag , +.IR mode ) +had been called, and the returned file descriptor, if not +.IR fildes , +had been changed to +.IR fildes ) +when a new process is spawned using this file actions object. If +.IR fildes +was already an open file descriptor, it shall be closed before the new +file is opened. +.P +The string described by +.IR path +shall be copied by the +\fIposix_spawn_file_actions_addopen\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIposix_spawn_file_actions_addopen\fR() +function shall fail if: +.TP +.BR EBADF +The value specified by +.IR fildes +is negative or greater than or equal to +{OPEN_MAX}. +.P +The +\fIposix_spawn_file_actions_addclose\fR() +function shall fail if: +.TP +.BR EBADF +The value specified by +.IR fildes +is negative. +.br +.P +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +is invalid. +.TP +.BR ENOMEM +Insufficient memory exists to add to the spawn file actions object. +.P +It shall not be considered an error for the +.IR fildes +argument passed to these functions to specify a file descriptor for +which the specified operation could not be performed at the time of the +call. Any such error will be detected when the associated file actions +object is later used during a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be provided +on all implementations. +.P +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIposix_spawn_file_actions_addclose\fR() +with an arbitrary integer risks non-conforming behavior, and this +function can only portably be used to close file descriptor values that +the application has obtained through explicit actions, or for the three +file descriptors corresponding to the standard file streams. In order +to avoid a race condition of leaking an unintended file descriptor +into a child process, an application should consider opening all file +descriptors with the FD_CLOEXEC bit set unless the file descriptor is +intended to be inherited across +.IR exec . +.SH RATIONALE +A spawn file actions object may be initialized to contain an ordered +sequence of +\fIclose\fR(), +\fIdup2\fR(), +and +\fIopen\fR() +operations to be used by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +to arrive at the set of open file descriptors inherited by the spawned +process from the set of open file descriptors in the parent at the time +of the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +call. It had been suggested that the +\fIclose\fR() +and +\fIdup2\fR() +operations alone are sufficient to rearrange file descriptors, and that +files which need to be opened for use by the spawned process can be +handled either by having the calling process open them before the +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +call (and close them after), or by passing pathnames to the spawned +process (in +.IR argv ) +so that it may open them itself. The standard developers recommend that +applications use one of these two methods when practical, since +detailed error status on a failed open operation is always available to +the application this way. However, the standard developers feel that +allowing a spawn file actions object to specify open operations is +still appropriate because: +.IP " 1." 4 +It is consistent with equivalent POSIX.5 (Ada) functionality. +.IP " 2." 4 +It supports the I/O redirection paradigm commonly employed by POSIX +programs designed to be invoked from a shell. When such a program is +the child process, it may not be designed to open files on its own. +.IP " 3." 4 +It allows file opens that might otherwise fail or violate file +ownership/access rights if executed by the parent process. +.P +Regarding 2. above, note that the spawn open file action provides to +\fIposix_spawn\fR() +and +\fIposix_spawnp\fR() +the same capability that the shell redirection operators provide to +\fIsystem\fR(), +only without the intervening execution of a shell; for example: +.sp +.RS 4 +.nf + +system ("myprog \fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawn_file_actions_adddup2.3p b/upstream/archlinux/man3p/posix_spawn_file_actions_adddup2.3p new file mode 100644 index 00000000..10a64e1f --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawn_file_actions_adddup2.3p @@ -0,0 +1,137 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDDUP2 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawn_file_actions_adddup2 +\(em add dup2 action to spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t + *\fIfile_actions\fP, int \fIfildes\fP, int \fInewfildes\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawn_file_actions_adddup2\fR() +function shall add a +\fIdup2\fR() +action to the object referenced by +.IR file_actions +that shall cause the file descriptor +.IR fildes +to be duplicated as +.IR newfildes +(as if +.IR dup2 (\c +.IR fildes , +.IR newfildes ) +had been called) when a new process is spawned using this file actions +object. +.P +A spawn file actions object is as defined in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_spawn_file_actions_adddup2\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIposix_spawn_file_actions_adddup2\fR() +function shall fail if: +.TP +.BR EBADF +The value specified by +.IR fildes +or +.IR newfildes +is negative or greater than or equal to +{OPEN_MAX}. +.TP +.BR ENOMEM +Insufficient memory exists to add to the spawn file actions object. +.P +The +\fIposix_spawn_file_actions_adddup2\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +is invalid. +.P +It shall not be considered an error for the +.IR fildes +argument passed to the +\fIposix_spawn_file_actions_adddup2\fR() +function to specify a file descriptor for which the specified operation +could not be performed at the time of the call. Any such error will be +detected when the associated file actions object is later used during a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +operation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIposix_spawn_file_actions_adddup2\fR() +function is part of the Spawn option and need not be +provided on all implementations. +.P +Implementations may use file descriptors that must be inherited into +child processes for the child process to remain conforming, such as for +message catalog or tracing purposes. Therefore, an application that calls +\fIposix_spawn_file_actions_adddup2\fR() +with an arbitrary integer for +.IR newfildes +risks non-conforming behavior, and this function can only portably be +used to overwrite file descriptor values that the application has obtained +through explicit actions, or for the three file descriptors corresponding +to the standard file streams. In order to avoid a race condition of +leaking an unintended file descriptor into a child process, an application +should consider opening all file descriptors with the FD_CLOEXEC bit +set unless the file descriptor is intended to be inherited across +.IR exec . +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIdup\fR\^(\|)", +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawn_file_actions_addopen.3p b/upstream/archlinux/man3p/posix_spawn_file_actions_addopen.3p new file mode 100644 index 00000000..154fff6e --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawn_file_actions_addopen.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_ADDOPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawn_file_actions_addopen +\(em add open action to spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t + *restrict \fIfile_actions\fP, int \fIfildes\fP, + const char *restrict \fIpath\fP, int \fIoflag\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawn_file_actions_destroy.3p b/upstream/archlinux/man3p/posix_spawn_file_actions_destroy.3p new file mode 100644 index 00000000..cf66a0ed --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawn_file_actions_destroy.3p @@ -0,0 +1,111 @@ +'\" et +.TH POSIX_SPAWN_FILE_ACTIONS_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawn_file_actions_destroy, +posix_spawn_file_actions_init +\(em destroy and initialize spawn file actions object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t + *\fIfile_actions\fP); +int posix_spawn_file_actions_init(posix_spawn_file_actions_t + *\fIfile_actions\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawn_file_actions_destroy\fR() +function shall destroy the object referenced by +.IR file_actions ; +the object becomes, in effect, uninitialized. An implementation may +cause +\fIposix_spawn_file_actions_destroy\fR() +to set the object referenced by +.IR file_actions +to an invalid value. A destroyed spawn file actions object can be +reinitialized using +\fIposix_spawn_file_actions_init\fR(); +the results of otherwise referencing the object after it has been +destroyed are undefined. +.P +The +\fIposix_spawn_file_actions_init\fR() +function shall initialize the object referenced by +.IR file_actions +to contain no file actions for +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +to perform. +.P +A spawn file actions object is as defined in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.P +The effect of initializing an already initialized spawn file actions +object is undefined. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIposix_spawn_file_actions_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the spawn file actions object. +.P +The +\fIposix_spawn_file_actions_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR file_actions +is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawn_file_actions_addclose\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.br +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_destroy.3p b/upstream/archlinux/man3p/posix_spawnattr_destroy.3p new file mode 100644 index 00000000..8764a78e --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_destroy.3p @@ -0,0 +1,153 @@ +'\" et +.TH POSIX_SPAWNATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_destroy, +posix_spawnattr_init +\(em destroy and initialize spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_destroy(posix_spawnattr_t *\fIattr\fP); +int posix_spawnattr_init(posix_spawnattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_destroy\fR() +function shall destroy a spawn attributes object. A destroyed +.IR attr +attributes object can be reinitialized using +\fIposix_spawnattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. An implementation may cause +\fIposix_spawnattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +The +\fIposix_spawnattr_init\fR() +function shall initialize a spawn attributes object +.IR attr +with the default value for all of the individual attributes used by the +implementation. Results are undefined if +\fIposix_spawnattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +A spawn attributes object is of type +.BR posix_spawnattr_t +(defined in +.IR ) +and is used to specify the inheritance of process attributes across a +spawn operation. POSIX.1\(hy2008 does not define comparison or assignment +operators for the type +.BR posix_spawnattr_t . +.P +Each implementation shall document the individual attributes it uses +and their default values unless these values are defined by POSIX.1\(hy2008. +Attributes not defined by POSIX.1\(hy2008, their default values, and the names of +the associated functions to get and set those attribute values are +implementation-defined. +.P +The resulting spawn attributes object (possibly modified by setting +individual attribute values), is used to modify the behavior of +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(). +After a spawn attributes object has been used to spawn a process by a +call to a +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(), +any function affecting the attributes object (including destruction) +shall not affect any process that has been spawned in this way. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_destroy\fR() +and +\fIposix_spawnattr_init\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIposix_spawnattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the spawn attributes object. +.P +The +\fIposix_spawnattr_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by attr is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +The original spawn interface proposed in POSIX.1\(hy2008 defined the attributes +that specify the inheritance of process attributes across a spawn +operation as a structure. In order to be able to separate optional +individual attributes under their appropriate options (that is, the +.IR spawn-schedparam +and +.IR spawn-schedpolicy +attributes depending upon the Process Scheduling option), and also for +extensibility and consistency with the newer POSIX interfaces, the +attributes interface has been changed to an opaque data type. This +interface now consists of the type +.BR posix_spawnattr_t , +representing a spawn attributes object, together with associated +functions to initialize or destroy the attributes object, and to set or +get each individual attribute. Although the new object-oriented +interface is more verbose than the original structure, it is simple to +use, more extensible, and easy to implement. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_getflags.3p b/upstream/archlinux/man3p/posix_spawnattr_getflags.3p new file mode 100644 index 00000000..b8c21846 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_getflags.3p @@ -0,0 +1,131 @@ +'\" et +.TH POSIX_SPAWNATTR_GETFLAGS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_getflags, +posix_spawnattr_setflags +\(em get and set the spawn-flags attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_getflags(const posix_spawnattr_t *restrict \fIattr\fP, + short *restrict \fIflags\fP); +int posix_spawnattr_setflags(posix_spawnattr_t *\fIattr\fP, short \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getflags\fR() +function shall obtain the value of the +.IR spawn-flags +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setflags\fR() +function shall set the +.IR spawn-flags +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-flags +attribute is used to indicate which process attributes are to be +changed in the new process image when invoking +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR(). +It is the bitwise-inclusive OR of zero or more of the following flags: +.P +.nf +POSIX_SPAWN_RESETIDS +POSIX_SPAWN_SETPGROUP +POSIX_SPAWN_SETSIGDEF +POSIX_SPAWN_SETSIGMASK +POSIX_SPAWN_SETSCHEDPARAM +POSIX_SPAWN_SETSCHEDULER +.fi +.P +These flags are defined in +.IR . +The default value of this attribute shall be as if no flags were set. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getflags\fR() +shall return zero and store the value of the +.IR spawn-flags +attribute of +.IR attr +into the object referenced by the +.IR flags +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setflags\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setflags\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_getpgroup.3p b/upstream/archlinux/man3p/posix_spawnattr_getpgroup.3p new file mode 100644 index 00000000..523c8907 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_getpgroup.3p @@ -0,0 +1,116 @@ +'\" et +.TH POSIX_SPAWNATTR_GETPGROUP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_getpgroup, +posix_spawnattr_setpgroup +\(em get and set the spawn-pgroup attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_getpgroup(const posix_spawnattr_t *restrict \fIattr\fP, + pid_t *restrict \fIpgroup\fP); +int posix_spawnattr_setpgroup(posix_spawnattr_t *\fIattr\fP, pid_t \fIpgroup\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getpgroup\fR() +function shall obtain the value of the +.IR spawn-pgroup +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setpgroup\fR() +function shall set the +.IR spawn-pgroup +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-pgroup +attribute represents the process group to be joined by the new process +image in a spawn operation (if POSIX_SPAWN_SETPGROUP is set in the +.IR spawn-flags +attribute). The default value of this attribute shall be zero. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getpgroup\fR() +shall return zero and store the value of the +.IR spawn-pgroup +attribute of +.IR attr +into the object referenced by the +.IR pgroup +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setpgroup\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setpgroup\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_getschedparam.3p b/upstream/archlinux/man3p/posix_spawnattr_getschedparam.3p new file mode 100644 index 00000000..c5da4cd5 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_getschedparam.3p @@ -0,0 +1,121 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSCHEDPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_getschedparam, +posix_spawnattr_setschedparam +\(em get and set the spawn-schedparam attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getschedparam(const posix_spawnattr_t + *restrict \fIattr\fP, struct sched_param *restrict \fIschedparam\fP); +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIschedparam\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getschedparam\fR() +function shall obtain the value of the +.IR spawn-schedparam +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setschedparam\fR() +function shall set the +.IR spawn-schedparam +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-schedparam +attribute represents the scheduling parameters to be assigned to the +new process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER or +POSIX_SPAWN_SETSCHEDPARAM is set +in the +.IR spawn-flags +attribute). The default value of this attribute is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getschedparam\fR() +shall return zero and store the value of the +.IR spawn-schedparam +attribute of +.IR attr +into the object referenced by the +.IR schedparam +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setschedparam\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setschedparam\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn and Process Scheduling options +and need not be provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_getschedpolicy.3p b/upstream/archlinux/man3p/posix_spawnattr_getschedpolicy.3p new file mode 100644 index 00000000..eaad0bc5 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_getschedpolicy.3p @@ -0,0 +1,120 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSCHEDPOLICY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_getschedpolicy, +posix_spawnattr_setschedpolicy +\(em get and set the spawn-schedpolicy attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getschedpolicy(const posix_spawnattr_t + *restrict \fIattr\fP, int *restrict \fIschedpolicy\fP); +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *\fIattr\fP, + int \fIschedpolicy\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getschedpolicy\fR() +function shall obtain the value of the +.IR spawn-schedpolicy +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setschedpolicy\fR() +function shall set the +.IR spawn-schedpolicy +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-schedpolicy +attribute represents the scheduling policy to be assigned to the new +process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER is set +in the +.IR spawn-flags +attribute). The default value of this attribute is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getschedpolicy\fR() +shall return zero and store the value of the +.IR spawn-schedpolicy +attribute of +.IR attr +into the object referenced by the +.IR schedpolicy +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setschedpolicy\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setschedpolicy\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn and Process Scheduling options +and need not be provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_getsigdefault.3p b/upstream/archlinux/man3p/posix_spawnattr_getsigdefault.3p new file mode 100644 index 00000000..71898703 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_getsigdefault.3p @@ -0,0 +1,121 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSIGDEFAULT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_getsigdefault, +posix_spawnattr_setsigdefault +\(em get and set the spawn-sigdefault attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getsigdefault(const posix_spawnattr_t + *restrict \fIattr\fP, sigset_t *restrict \fIsigdefault\fP); +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigdefault\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getsigdefault\fR() +function shall obtain the value of the +.IR spawn-sigdefault +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setsigdefault\fR() +function shall set the +.IR spawn-sigdefault +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-sigdefault +attribute represents the set of signals to be forced to default signal +handling in the new process image (if POSIX_SPAWN_SETSIGDEF is set in +the +.IR spawn-flags +attribute) by a spawn operation. The default value of this attribute +shall be an empty signal set. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getsigdefault\fR() +shall return zero and store the value of the +.IR spawn-sigdefault +attribute of +.IR attr +into the object referenced by the +.IR sigdefault +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setsigdefault\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setsigdefault\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_getsigmask.3p b/upstream/archlinux/man3p/posix_spawnattr_getsigmask.3p new file mode 100644 index 00000000..93eac253 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_getsigmask.3p @@ -0,0 +1,119 @@ +'\" et +.TH POSIX_SPAWNATTR_GETSIGMASK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_getsigmask, +posix_spawnattr_setsigmask +\(em get and set the spawn-sigmask attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_getsigmask(const posix_spawnattr_t *restrict \fIattr\fP, + sigset_t *restrict \fIsigmask\fP); +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigmask\fP); +.fi +.SH DESCRIPTION +The +\fIposix_spawnattr_getsigmask\fR() +function shall obtain the value of the +.IR spawn-sigmask +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIposix_spawnattr_setsigmask\fR() +function shall set the +.IR spawn-sigmask +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR spawn-sigmask +attribute represents the signal mask in effect in the new process image +of a spawn operation (if POSIX_SPAWN_SETSIGMASK is set in the +.IR spawn-flags +attribute). The default value of this attribute is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIposix_spawnattr_getsigmask\fR() +shall return zero and store the value of the +.IR spawn-sigmask +attribute of +.IR attr +into the object referenced by the +.IR sigmask +parameter; otherwise, an error number shall be returned to indicate the +error. +.P +Upon successful completion, +\fIposix_spawnattr_setsigmask\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR attr +is invalid. +.P +The +\fIposix_spawnattr_setsigmask\fR() +function may fail if: +.TP +.BR EINVAL +The value of the attribute being set is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are part of the Spawn option and need not be +provided on all implementations. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_spawn\fR\^(\|)", +.IR "\fIposix_spawnattr_destroy\fR\^(\|)", +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)", +.IR "\fIposix_spawnattr_getflags\fR\^(\|)", +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)", +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_init.3p b/upstream/archlinux/man3p/posix_spawnattr_init.3p new file mode 100644 index 00000000..9436524d --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_init.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_init +\(em initialize the spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_init(posix_spawnattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_setflags.3p b/upstream/archlinux/man3p/posix_spawnattr_setflags.3p new file mode 100644 index 00000000..0248d1b8 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_setflags.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETFLAGS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_setflags +\(em set the spawn-flags attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_setflags(posix_spawnattr_t *\fIattr\fP, short \fIflags\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getflags\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_setpgroup.3p b/upstream/archlinux/man3p/posix_spawnattr_setpgroup.3p new file mode 100644 index 00000000..d2dd9acf --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_setpgroup.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_SPAWNATTR_SETPGROUP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_setpgroup +\(em set the spawn-pgroup attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnattr_setpgroup(posix_spawnattr_t *\fIattr\fP, pid_t \fIpgroup\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getpgroup\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_setschedparam.3p b/upstream/archlinux/man3p/posix_spawnattr_setschedparam.3p new file mode 100644 index 00000000..5e4c0761 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_setschedparam.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSCHEDPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_setschedparam +\(em set the spawn-schedparam attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setschedparam(posix_spawnattr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIschedparam\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getschedparam\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_setschedpolicy.3p b/upstream/archlinux/man3p/posix_spawnattr_setschedpolicy.3p new file mode 100644 index 00000000..ba2d6865 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_setschedpolicy.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSCHEDPOLICY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_setschedpolicy +\(em set the spawn-schedpolicy attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setschedpolicy(posix_spawnattr_t *\fIattr\fP, + int \fIschedpolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getschedpolicy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_setsigdefault.3p b/upstream/archlinux/man3p/posix_spawnattr_setsigdefault.3p new file mode 100644 index 00000000..ae373617 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_setsigdefault.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSIGDEFAULT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_setsigdefault +\(em set the spawn-sigdefault attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setsigdefault(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigdefault\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getsigdefault\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnattr_setsigmask.3p b/upstream/archlinux/man3p/posix_spawnattr_setsigmask.3p new file mode 100644 index 00000000..581154f2 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnattr_setsigmask.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_SPAWNATTR_SETSIGMASK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnattr_setsigmask +\(em set the spawn-sigmask attribute of a spawn attributes object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_spawnattr_setsigmask(posix_spawnattr_t *restrict \fIattr\fP, + const sigset_t *restrict \fIsigmask\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawnattr_getsigmask\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_spawnp.3p b/upstream/archlinux/man3p/posix_spawnp.3p new file mode 100644 index 00000000..359128d2 --- /dev/null +++ b/upstream/archlinux/man3p/posix_spawnp.3p @@ -0,0 +1,44 @@ +'\" et +.TH POSIX_SPAWNP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_spawnp +\(em spawn a process +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_spawnp(pid_t *restrict \fIpid\fP, const char *restrict \fIfile\fP, + const posix_spawn_file_actions_t *\fIfile_actions\fP, + const posix_spawnattr_t *restrict \fIattrp\fP, + char *const \fIargv\fP[restrict], char *const \fIenvp\fP[restrict]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_spawn\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_destroy.3p b/upstream/archlinux/man3p/posix_trace_attr_destroy.3p new file mode 100644 index 00000000..bc57c946 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_destroy.3p @@ -0,0 +1,127 @@ +'\" et +.TH POSIX_TRACE_ATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_destroy, +posix_trace_attr_init +\(em destroy and initialize the trace stream attributes object +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_destroy(trace_attr_t *\fIattr\fP); +int posix_trace_attr_init(trace_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_destroy\fR() +function shall destroy an initialized trace attributes object. +A destroyed +.IR attr +attributes object can be reinitialized using +\fIposix_trace_attr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIposix_trace_attr_init\fR() +function shall initialize a trace attributes object +.IR attr +with the default value for all of the individual attributes used by a +given implementation. The read-only +.IR generation-version +and +.IR clock-resolution +attributes of the newly initialized trace attributes object shall be +set to their appropriate values (see +.IR "Section 2.11.1.2" ", " "posix_trace_status_info Structure"). +.P +Results are undefined if +\fIposix_trace_attr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +Implementations may add extensions to the trace attributes object +structure as permitted in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 2" ", " "Conformance". +.P +The resulting attributes object (possibly modified by setting +individual attributes values), when used by +\fIposix_trace_create\fR(), +defines the attributes of the trace stream created. A single +attributes object can be used in multiple calls to +\fIposix_trace_create\fR(). +After one or more trace streams have been created using an attributes +object, any function affecting that attributes object, including +destruction, shall not affect any trace stream previously created. An +initialized attributes object also serves to receive the attributes of +an existing trace stream or trace log when calling the +\fIposix_trace_get_attr\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.SH ERRORS +The +\fIposix_trace_attr_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR attr +is invalid. +.P +The +\fIposix_trace_attr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the trace attributes object. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_attr_destroy\fR() +and +\fIposix_trace_attr_init\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIuname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_getclockres.3p b/upstream/archlinux/man3p/posix_trace_attr_getclockres.3p new file mode 100644 index 00000000..9f814e6f --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_getclockres.3p @@ -0,0 +1,192 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETCLOCKRES "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_getclockres, +posix_trace_attr_getcreatetime, +posix_trace_attr_getgenversion, +posix_trace_attr_getname, +posix_trace_attr_setname +\(em retrieve and set information about a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_getclockres(const trace_attr_t *\fIattr\fP, + struct timespec *\fIresolution\fP); +int posix_trace_attr_getcreatetime(const trace_attr_t *\fIattr\fP, + struct timespec *\fIcreatetime\fP); +.P +#include +.P +int posix_trace_attr_getgenversion(const trace_attr_t *\fIattr\fP, + char *\fIgenversion\fP); +int posix_trace_attr_getname(const trace_attr_t *\fIattr\fP, + char *\fItracename\fP); +int posix_trace_attr_setname(trace_attr_t *\fIattr\fP, + const char *\fItracename\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_getclockres\fR() +function shall copy the clock resolution of the clock used to generate +timestamps from the +.IR clock-resolution +attribute of the attributes object pointed to by the +.IR attr +argument into the structure pointed to by the +.IR resolution +argument. +.P +The +\fIposix_trace_attr_getcreatetime\fR() +function shall copy the trace stream creation time from the +.IR creation-time +attribute of the attributes object pointed to by the +.IR attr +argument into the structure pointed to by the +.IR createtime +argument. The +.IR creation-time +attribute shall represent the time of creation of the trace stream. +.P +The +\fIposix_trace_attr_getgenversion\fR() +function shall copy the string containing version information from the +.IR generation-version +attribute of the attributes object pointed to by the +.IR attr +argument into the string pointed to by the +.IR genversion +argument. The +.IR genversion +argument shall be the address of a character array which can store at +least +{TRACE_NAME_MAX} +characters. +.P +The +\fIposix_trace_attr_getname\fR() +function shall copy the string containing the trace name from the +.IR trace-name +attribute of the attributes object pointed to by the +.IR attr +argument into the string pointed to by the +.IR tracename +argument. The +.IR tracename +argument shall be the address of a character array which can store at +least +{TRACE_NAME_MAX} +characters. +.P +The +\fIposix_trace_attr_setname\fR() +function shall set the name in the +.IR trace-name +attribute of the attributes object pointed to by the +.IR attr +argument, using the trace name string supplied by the +.IR tracename +argument. If the supplied string contains more than +{TRACE_NAME_MAX} +characters, the name copied into the +.IR trace-name +attribute may be truncated to one less than the length of +{TRACE_NAME_MAX} +characters. The default value is a null string. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, the +\fIposix_trace_attr_getclockres\fR() +function stores the +.IR clock-resolution +attribute value in the object pointed to by +.IR resolution . +Otherwise, the content of this object is unspecified. +.P +If successful, the +\fIposix_trace_attr_getcreatetime\fR() +function stores the trace stream creation time in the object pointed to +by +.IR createtime . +Otherwise, the content of this object is unspecified. +.P +If successful, the +\fIposix_trace_attr_getgenversion\fR() +function stores the trace version information in the string pointed to +by +.IR genversion . +Otherwise, the content of this string is unspecified. +.P +If successful, the +\fIposix_trace_attr_getname\fR() +function stores the trace name in the string pointed to by +.IR tracename . +Otherwise, the content of this string is unspecified. +.SH ERRORS +The +\fIposix_trace_attr_getclockres\fR(), +\fIposix_trace_attr_getcreatetime\fR(), +\fIposix_trace_attr_getgenversion\fR(), +and +\fIposix_trace_attr_getname\fR() +functions may fail if: +.TP +.BR EINVAL +The value specified by one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_attr_getclockres\fR(), +\fIposix_trace_attr_getcreatetime\fR(), +\fIposix_trace_attr_getgenversion\fR(), +\fIposix_trace_attr_getname\fR(), +and +\fIposix_trace_attr_setname\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIuname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_getinherited.3p b/upstream/archlinux/man3p/posix_trace_attr_getinherited.3p new file mode 100644 index 00000000..4e41667c --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_getinherited.3p @@ -0,0 +1,279 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETINHERITED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +.ad l +posix_trace_attr_getinherited, +posix_trace_attr_getlogfullpolicy, +posix_trace_attr_getstreamfullpolicy, +posix_trace_attr_setinherited, +posix_trace_attr_setlogfullpolicy, +posix_trace_attr_setstreamfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_getinherited(const trace_attr_t *restrict \fIattr\fP, + int *restrict \fIinheritancepolicy\fP); +int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict \fIattr\fP, + int *restrict \fIlogpolicy\fP); +int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict + \fIattr\fP, int *restrict \fIstreampolicy\fP); +int posix_trace_attr_setinherited(trace_attr_t *\fIattr\fP, + int \fIinheritancepolicy\fP); +int posix_trace_attr_setlogfullpolicy(trace_attr_t *\fIattr\fP, + int \fIlogpolicy\fP); +int posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fIattr\fP, + int \fIstreampolicy\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_getinherited\fR() +and +\fIposix_trace_attr_setinherited\fR() +functions, respectively, shall get and set the inheritance policy +stored in the +.IR inheritance +attribute for traced processes across the +\fIfork\fR() +and +\fIspawn\fR() +operations. The +.IR inheritance +attribute of the attributes object pointed to by the +.IR attr +argument shall be set to one of the following values defined by +manifest constants in the +.IR +header: +.IP POSIX_TRACE_CLOSE_FOR_CHILD 6 +.br +After a +\fIfork\fR() +or +\fIspawn\fR() +operation, the child shall not be traced, and tracing of the parent +shall continue. +.IP POSIX_TRACE_INHERITED 6 +.br +After a +\fIfork\fR() +or +\fIspawn\fR() +operation, if the parent is being traced, its child shall be +concurrently traced using the same trace stream. +.P +The default value for the +.IR inheritance +attribute is POSIX_TRACE_CLOSE_FOR_CHILD. +.P +The +\fIposix_trace_attr_getlogfullpolicy\fR() +and +\fIposix_trace_attr_setlogfullpolicy\fR() +functions, respectively, shall get and set the trace log full policy +stored in the +.IR log-full-policy +attribute of the attributes object pointed to by the +.IR attr +argument. +.P +The +.IR log-full-policy +attribute shall be set to one of the following values defined by +manifest constants in the +.IR +header: +.IP POSIX_TRACE_LOOP 6 +.br +The trace log shall loop until the associated trace stream is stopped. +This policy means that when the trace log gets full, the file system +shall reuse the resources allocated to the oldest trace events that +were recorded. In this way, the trace log will always contain the most +recent trace events flushed. +.IP POSIX_TRACE_UNTIL_FULL 6 +.br +The trace stream shall be flushed to the trace log until the trace log +is full. This condition can be deduced from the +.IR posix_log_full_status +member status (see the +.BR posix_trace_status_info +structure defined in +.IR ). +The last recorded trace event shall be the POSIX_TRACE_STOP trace event. +.IP POSIX_TRACE_APPEND 6 +.br +The associated trace stream shall be flushed to the trace log without +log size limitation. If the application specifies POSIX_TRACE_APPEND, +the implementation shall ignore the +.IR log-max-size +attribute. +.P +The default value for the +.IR log-full-policy +attribute is POSIX_TRACE_LOOP. +.P +The +\fIposix_trace_attr_getstreamfullpolicy\fR() +and +\fIposix_trace_attr_setstreamfullpolicy\fR() +functions, respectively, shall get and set the trace stream full policy +stored in the +.IR stream-full-policy +attribute of the attributes object pointed to by the +.IR attr +argument. +.P +The +.IR stream-full-policy +attribute shall be set to one of the following values defined by +manifest constants in the +.IR +header: +.IP POSIX_TRACE_LOOP 6 +.br +The trace stream shall loop until explicitly stopped by the +\fIposix_trace_stop\fR() +function. This policy means that when the trace stream is full, the +trace system shall reuse the resources allocated to the oldest trace +events recorded. In this way, the trace stream will always contain the +most recent trace events recorded. +.IP POSIX_TRACE_UNTIL_FULL 6 +.br +The trace stream will run until the trace stream resources are +exhausted. Then the trace stream will stop. This condition can be +deduced from +.IR posix_stream_status +and +.IR posix_stream_full_status +(see the +.BR posix_trace_status_info +structure defined in +.IR ). +When this trace stream is read, a POSIX_TRACE_STOP trace +event shall be reported after reporting the last recorded trace event. +The trace system shall reuse the resources allocated to any trace +events already reported\(emsee the +\fIposix_trace_getnext_event\fR(), +\fIposix_trace_trygetnext_event\fR(), +and +\fIposix_trace_timedgetnext_event\fR() +functions\(emor already flushed for an active trace stream with log if +the Trace Log option is supported; see the +\fIposix_trace_flush\fR() +function. The trace system shall restart the trace stream when it is +empty and may restart it sooner. A POSIX_TRACE_START trace event shall +be reported before reporting the next recorded trace event. +.IP POSIX_TRACE_FLUSH 6 +.br +If the Trace Log option is supported, this policy is identical to the +POSIX_TRACE_UNTIL_FULL trace stream full policy except that the trace +stream shall be flushed regularly as if +\fIposix_trace_flush\fR() +had been explicitly called. Defining this policy for an active trace +stream without log shall be invalid. +.P +The default value for the +.IR stream-full-policy +attribute shall be POSIX_TRACE_LOOP for an active trace stream without +log. +.P +If the Trace Log option is supported, the default value for the +.IR stream-full-policy +attribute shall be POSIX_TRACE_FLUSH for an active trace stream with +log. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, the +\fIposix_trace_attr_getinherited\fR() +function shall store the +.IR inheritance +attribute value in the object pointed to by +.IR inheritancepolicy . +Otherwise, the content of this object is undefined. +.P +If successful, the +\fIposix_trace_attr_getlogfullpolicy\fR() +function shall store the +.IR log-full-policy +attribute value in the object pointed to by +.IR logpolicy . +Otherwise, the content of this object is undefined. +.P +If successful, the +\fIposix_trace_attr_getstreamfullpolicy\fR() +function shall store the +.IR stream-full-policy +attribute value in the object pointed to by +.IR streampolicy . +Otherwise, the content of this object is undefined. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by at least one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The following functions: +.sp +.RS +.nf +\fIposix_trace_attr_getinherited\fR() +\fIposix_trace_attr_getlogfullpolicy\fR() +\fIposix_trace_attr_getstreamfullpolicy\fR() +\fIposix_trace_attr_setinherited\fR() +\fIposix_trace_attr_setlogfullpolicy\fR() +\fIposix_trace_attr_setstreamfullpolicy\fR() +.fi +.RE +.P +may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIfork\fR\^(\|)", +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_getlogsize.3p b/upstream/archlinux/man3p/posix_trace_attr_getlogsize.3p new file mode 100644 index 00000000..206657a1 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_getlogsize.3p @@ -0,0 +1,267 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETLOGSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +.ad l +posix_trace_attr_getlogsize, +posix_trace_attr_getmaxdatasize, +posix_trace_attr_getmaxsystemeventsize, +posix_trace_attr_getmaxusereventsize, +posix_trace_attr_getstreamsize, +posix_trace_attr_setlogsize, +posix_trace_attr_setmaxdatasize, +posix_trace_attr_setstreamsize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.ad b +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_getlogsize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIlogsize\fP); +int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fImaxdatasize\fP); +int posix_trace_attr_getmaxsystemeventsize( + const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIeventsize\fP); +int posix_trace_attr_getmaxusereventsize( + const trace_attr_t *restrict \fIattr\fP, + size_t \fIdata_len\fP, size_t *restrict \fIeventsize\fP); +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIstreamsize\fP); +int posix_trace_attr_setlogsize(trace_attr_t *\fIattr\fP, + size_t \fIlogsize\fP); +int posix_trace_attr_setmaxdatasize(trace_attr_t *\fIattr\fP, + size_t \fImaxdatasize\fP); +int posix_trace_attr_setstreamsize(trace_attr_t *\fIattr\fP, + size_t \fIstreamsize\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_attr_getlogsize\fR() +function shall copy the log size, in bytes, from the +.IR log-max-size +attribute of the attributes object pointed to by the +.IR attr +argument into the variable pointed to by the +.IR logsize +argument. This log size is the maximum total of bytes that shall be +allocated for system and user trace events in the trace log. The +default value for the +.IR log-max-size +attribute is implementation-defined. +.P +The +\fIposix_trace_attr_setlogsize\fR() +function shall set the maximum allowed size, in bytes, in the +.IR log-max-size +attribute of the attributes object pointed to by the +.IR attr +argument, using the size value supplied by the +.IR logsize +argument. +.P +The trace log size shall be used if the +.IR log-full-policy +attribute is set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL. If the +.IR log-full-policy +attribute is set to POSIX_TRACE_APPEND, the implementation shall ignore +the +.IR log-max-size +attribute. +.P +The +\fIposix_trace_attr_getmaxdatasize\fR() +function shall copy the maximum user trace event data size, in bytes, +from the +.IR max-data-size +attribute of the attributes object pointed to by the +.IR attr +argument into the variable pointed to by the +.IR maxdatasize +argument. The default value for the +.IR max-data-size +attribute is implementation-defined. +.P +The +\fIposix_trace_attr_getmaxsystemeventsize\fR() +function shall calculate the maximum memory size, in bytes, required to +store a single system trace event. This value is calculated for the +trace stream attributes object pointed to by the +.IR attr +argument and is returned in the variable pointed to by the +.IR eventsize +argument. +.P +The values returned as the maximum memory sizes of the user and system +trace events shall be such that if the sum of the maximum memory sizes +of a set of the trace events that may be recorded in a trace stream is +less than or equal to the +.IR stream-min-size +attribute of that trace stream, the system provides the necessary +resources for recording all those trace events, without loss. +.P +The +\fIposix_trace_attr_getmaxusereventsize\fR() +function shall calculate the maximum memory size, in bytes, required to +store a single user trace event generated by a call to +\fIposix_trace_event\fR() +with a +.IR data_len +parameter equal to the +.IR data_len +value specified in this call. This value is calculated for the trace +stream attributes object pointed to by the +.IR attr +argument and is returned in the variable pointed to by the +.IR eventsize +argument. +.P +The +\fIposix_trace_attr_getstreamsize\fR() +function shall copy the stream size, in bytes, from the +.IR stream-min-size +attribute of the attributes object pointed to by the +.IR attr +argument into the variable pointed to by the +.IR streamsize +argument. +.P +This stream size is the current total memory size reserved for system +and user trace events in the trace stream. The default value for the +.IR stream-min-size +attribute is implementation-defined. The stream size refers to memory +used to store trace event records. Other stream data (for example, +trace attribute values) shall not be included in this size. +.P +The +\fIposix_trace_attr_setmaxdatasize\fR() +function shall set the maximum allowed size, in bytes, in the +.IR max-data-size +attribute of the attributes object pointed to by the +.IR attr +argument, using the size value supplied by the +.IR maxdatasize +argument. This maximum size is the maximum allowed size for the user +data argument which may be passed to +\fIposix_trace_event\fR(). +The implementation shall be allowed to truncate data passed to +.IR trace_user_event +which is longer than +.IR maxdatasize . +.P +The +\fIposix_trace_attr_setstreamsize\fR() +function shall set the minimum allowed size, in bytes, in the +.IR stream-min-size +attribute of the attributes object pointed to by the +.IR attr +argument, using the size value supplied by the +.IR streamsize +argument. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_attr_getlogsize\fR() +function stores the maximum trace log allowed size in the object +pointed to by +.IR logsize , +if successful. +.P +The +\fIposix_trace_attr_getmaxdatasize\fR() +function stores the maximum trace event record memory size in the +object pointed to by +.IR maxdatasize , +if successful. +.P +The +\fIposix_trace_attr_getmaxsystemeventsize\fR() +function stores the maximum memory size to store a single system trace +event in the object pointed to by +.IR eventsize , +if successful. +.P +The +\fIposix_trace_attr_getmaxusereventsize\fR() +function stores the maximum memory size to store a single user trace +event in the object pointed to by +.IR eventsize , +if successful. +.P +The +\fIposix_trace_attr_getstreamsize\fR() +function stores the maximum trace stream allowed size in the object +pointed to by +.IR streamsize , +if successful. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The following functions: +.sp +.RS +.nf +\fIposix_trace_attr_getlogsize\fR() +\fIposix_trace_attr_getmaxdatasize\fR() +\fIposix_trace_attr_getmaxsystemeventsize\fR() +\fIposix_trace_attr_getmaxusereventsize\fR() +\fIposix_trace_attr_getstreamsize\fR() +\fIposix_trace_attr_setlogsize\fR() +\fIposix_trace_attr_setmaxdatasize\fR() +\fIposix_trace_attr_setstreamsize\fR() +.fi +.RE +.P +may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_getname.3p b/upstream/archlinux/man3p/posix_trace_attr_getname.3p new file mode 100644 index 00000000..c0a8cf07 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_getname.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_getname +\(em retrieve and set information about a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_getname(const trace_attr_t *\fIattr\fP, + char *\fItracename\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getclockres\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_getstreamfullpolicy.3p b/upstream/archlinux/man3p/posix_trace_attr_getstreamfullpolicy.3p new file mode 100644 index 00000000..e7495fe1 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_getstreamfullpolicy.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETSTREAMFULLPOLICY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_getstreamfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict + \fIattr\fP, int *restrict \fIstreampolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_getstreamsize.3p b/upstream/archlinux/man3p/posix_trace_attr_getstreamsize.3p new file mode 100644 index 00000000..7d4d6573 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_getstreamsize.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_ATTR_GETSTREAMSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_getstreamsize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_getstreamsize(const trace_attr_t *restrict \fIattr\fP, + size_t *restrict \fIstreamsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_init.3p b/upstream/archlinux/man3p/posix_trace_attr_init.3p new file mode 100644 index 00000000..839fc027 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_init.3p @@ -0,0 +1,41 @@ +'\" et +.TH POSIX_TRACE_ATTR_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_init +\(em initialize the trace stream attributes object +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_init(trace_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_setinherited.3p b/upstream/archlinux/man3p/posix_trace_attr_setinherited.3p new file mode 100644 index 00000000..ef773574 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_setinherited.3p @@ -0,0 +1,45 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETINHERITED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_setinherited, +posix_trace_attr_setlogfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_setinherited(trace_attr_t *\fIattr\fP, + int \fIinheritancepolicy\fP); +int posix_trace_attr_setlogfullpolicy(trace_attr_t *\fIattr\fP, + int \fIlogpolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_setlogsize.3p b/upstream/archlinux/man3p/posix_trace_attr_setlogsize.3p new file mode 100644 index 00000000..dfae320e --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_setlogsize.3p @@ -0,0 +1,46 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETLOGSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_setlogsize, +posix_trace_attr_setmaxdatasize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_setlogsize(trace_attr_t *\fIattr\fP, + size_t \fIlogsize\fP); +int posix_trace_attr_setmaxdatasize(trace_attr_t *\fIattr\fP, + size_t \fImaxdatasize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_setname.3p b/upstream/archlinux/man3p/posix_trace_attr_setname.3p new file mode 100644 index 00000000..a21fb46a --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_setname.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_setname +\(em retrieve and set information about a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_setname(trace_attr_t *\fIattr\fP, + const char *\fItracename\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getclockres\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_setstreamfullpolicy.3p b/upstream/archlinux/man3p/posix_trace_attr_setstreamfullpolicy.3p new file mode 100644 index 00000000..4071aef5 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_setstreamfullpolicy.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETSTREAMFULLPOLICY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_setstreamfullpolicy +\(em retrieve and set the behavior of a trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fIattr\fP, + int \fIstreampolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getinherited\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_attr_setstreamsize.3p b/upstream/archlinux/man3p/posix_trace_attr_setstreamsize.3p new file mode 100644 index 00000000..e271f261 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_attr_setstreamsize.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_ATTR_SETSTREAMSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_attr_setstreamsize +\(em retrieve and set trace stream size attributes +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_attr_setstreamsize(trace_attr_t *\fIattr\fP, + size_t \fIstreamsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_attr_getlogsize\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_clear.3p b/upstream/archlinux/man3p/posix_trace_clear.3p new file mode 100644 index 00000000..cf98991c --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_clear.3p @@ -0,0 +1,127 @@ +'\" et +.TH POSIX_TRACE_CLEAR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_clear +\(em clear trace stream and trace log +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_clear(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_clear\fR() +function shall reinitialize the trace stream identified by the argument +.IR trid +as if it were returning from the +\fIposix_trace_create\fR() +function, except that the same allocated resources shall be reused, the +mapping of trace event type identifiers to trace event names shall be +unchanged, and the trace stream status shall remain unchanged (that is, +if it was running, it remains running and if it was suspended, it +remains suspended). +.P +All trace events in the trace stream recorded before the call to +\fIposix_trace_clear\fR() +shall be lost. The +.IR posix_stream_full_status +status shall be set to POSIX_TRACE_NOT_FULL. +There is no guarantee that all trace events that occurred during the +\fIposix_trace_clear\fR() +call are recorded; the behavior with respect to trace points that may +occur during this call is unspecified. +.P +If the Trace Log option is supported and the trace stream has been +created with a log, the +\fIposix_trace_clear\fR() +function shall reinitialize the trace stream with the same behavior as +if the trace stream was created without the log, plus it shall +reinitialize the trace log associated with the trace stream identified +by the argument +.IR trid +as if it were returning from the +\fIposix_trace_create_withlog\fR() +function, except that the same allocated resources, for the trace log, +may be reused and the associated trace stream status remains unchanged. +The first trace event recorded in the trace log after the call to +\fIposix_trace_clear\fR() +shall be the same as the first trace event recorded in the active trace +stream after the call to +\fIposix_trace_clear\fR(). +The +.IR posix_log_full_status +status shall be set to POSIX_TRACE_NOT_FULL. There is no guarantee +that all trace events that occurred during the +\fIposix_trace_clear\fR() +call are recorded in the trace log; the behavior with respect to trace +points that may occur during this call is unspecified. If the log full +policy is POSIX_TRACE_APPEND, the effect of a call to this function is +unspecified for the trace log associated with the trace stream +identified by the +.IR trid +argument. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_trace_clear\fR() +function shall return a value of zero. Otherwise, it shall return the +corresponding error number. +.SH ERRORS +The +\fIposix_trace_clear\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR trid +argument does not correspond to an active trace stream. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_clear\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_close.3p b/upstream/archlinux/man3p/posix_trace_close.3p new file mode 100644 index 00000000..4e4d66fd --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_close.3p @@ -0,0 +1,175 @@ +'\" et +.TH POSIX_TRACE_CLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_close, +posix_trace_open, +posix_trace_rewind +\(em trace log management +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_close(trace_id_t \fItrid\fP); +int posix_trace_open(int \fIfile_desc\fP, trace_id_t *\fItrid\fP); +int posix_trace_rewind(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_close\fR() +function shall deallocate the trace log identifier indicated by +.IR trid , +and all of its associated resources. If there is no valid trace log +pointed to by the +.IR trid , +this function shall fail. +.P +The +\fIposix_trace_open\fR() +function shall allocate the necessary resources and establish the +connection between a trace log identified by the +.IR file_desc +argument and a trace stream identifier identified by the object pointed +to by the +.IR trid +argument. The +.IR file_desc +argument should be a valid open file descriptor that corresponds to a +trace log. The +.IR file_desc +argument shall be open for reading. The current trace event timestamp, +which specifies the timestamp of the trace event that will be read by +the next call to +\fIposix_trace_getnext_event\fR(), +shall be set to the timestamp of the oldest trace event recorded in the +trace log identified by +.IR trid . +.P +The +\fIposix_trace_open\fR() +function shall return a trace stream identifier in the variable +pointed to by the +.IR trid +argument, that may only be used by the following functions: +.TS +tab(!); +l l. +T{ +.nf +\fIposix_trace_close\fR() +\fIposix_trace_eventid_equal\fR() +\fIposix_trace_eventid_get_name\fR() +\fIposix_trace_eventtypelist_getnext_id\fR() +\fIposix_trace_eventtypelist_rewind\fR() +T}!T{ +.nf +\fIposix_trace_get_attr\fR() +\fIposix_trace_get_status\fR() +\fIposix_trace_getnext_event\fR() +\fIposix_trace_rewind\fR() +.fi +T} +.TE +.P +In particular, notice that the operations normally used by a trace +controller process, such as +\fIposix_trace_start\fR(), +\fIposix_trace_stop\fR(), +or +\fIposix_trace_shutdown\fR(), +cannot be invoked using the trace stream identifier returned by the +\fIposix_trace_open\fR() +function. +.P +The +\fIposix_trace_rewind\fR() +function shall reset the current trace event timestamp, which specifies +the timestamp of the trace event that will be read by the next call to +\fIposix_trace_getnext_event\fR(), +to the timestamp of the oldest trace event recorded in the trace log +identified by +.IR trid . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, the +\fIposix_trace_open\fR() +function stores the trace stream identifier value in the object pointed +to by +.IR trid . +.SH ERRORS +The +\fIposix_trace_open\fR() +function shall fail if: +.TP +.BR EINTR +The operation was interrupted by a signal and thus no trace log was +opened. +.TP +.BR EINVAL +The object pointed to by +.IR file_desc +does not correspond to a valid trace log. +.br +.P +The +\fIposix_trace_close\fR() +and +\fIposix_trace_rewind\fR() +functions may fail if: +.TP +.BR EINVAL +The object pointed to by +.IR trid +does not correspond to a valid trace log. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_close\fR(), +\fIposix_trace_open\fR(), +and +\fIposix_trace_rewind\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIposix_trace_get_filter\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_create.3p b/upstream/archlinux/man3p/posix_trace_create.3p new file mode 100644 index 00000000..d5876467 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_create.3p @@ -0,0 +1,452 @@ +'\" et +.TH POSIX_TRACE_CREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_create, +posix_trace_create_withlog, +posix_trace_flush, +posix_trace_shutdown +\(em trace stream initialization, flush, and shutdown from a process +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_create(pid_t \fIpid\fP, + const trace_attr_t *restrict \fIattr\fP, + trace_id_t *restrict \fItrid\fP); +int posix_trace_create_withlog(pid_t \fIpid\fP, + const trace_attr_t *restrict \fIattr\fP, int \fIfile_desc\fP, + trace_id_t *restrict \fItrid\fP); +int posix_trace_flush(trace_id_t \fItrid\fP); +int posix_trace_shutdown(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_create\fR() +function shall create an active trace stream. It allocates all the +resources needed by the trace stream being created for tracing the +process specified by +.IR pid +in accordance with the +.IR attr +argument. The +.IR attr +argument represents the initial attributes of the trace stream and +shall have been initialized by the function +\fIposix_trace_attr_init\fR() +prior to the +\fIposix_trace_create\fR() +call. If the argument +.IR attr +is NULL, the default attributes shall be used. The +.IR attr +attributes object shall be manipulated through a set of functions +described in the +.IR posix_trace_attr +family of functions. If the attributes of the object pointed to by +.IR attr +are modified later, the attributes of the trace stream shall not be +affected. The +.IR creation-time +attribute of the newly created trace stream shall be set to the value +of the system clock, if the Timers option is not supported, or to the +value of the CLOCK_REALTIME clock, if the Timers option is supported. +.P +The +.IR pid +argument represents the target process to be traced. If the process +executing this function does not have appropriate privileges to trace +the process identified by +.IR pid , +an error shall be returned. If the +.IR pid +argument is zero, the calling process shall be traced. +.P +The +\fIposix_trace_create\fR() +function shall store the trace stream identifier of the new trace +stream in the object pointed to by the +.IR trid +argument. This trace stream identifier shall be used in subsequent +calls to control tracing. The +.IR trid +argument may only be used by the following functions: +.TS +tab(!); +l l. +T{ +.nf +\fIposix_trace_clear\fR() +\fIposix_trace_eventid_equal\fR() +\fIposix_trace_eventid_get_name\fR() +\fIposix_trace_eventtypelist_getnext_id\fR() +\fIposix_trace_eventtypelist_rewind\fR() +\fIposix_trace_get_attr\fR() +\fIposix_trace_get_status\fR() +T}!T{ +.nf +\fIposix_trace_getnext_event\fR() +\fIposix_trace_shutdown\fR() +\fIposix_trace_start\fR() +\fIposix_trace_stop\fR() +\fIposix_trace_timedgetnext_event\fR() +\fIposix_trace_trid_eventid_open\fR() +\fIposix_trace_trygetnext_event\fR() +.fi +T} +.TE +.P +If the Trace Event Filter option is supported, the following additional +functions may use the +.IR trid +argument: +.TS +tab(!); +l l. +T{ +\fIposix_trace_get_filter\fR() +T}!T{ +\fIposix_trace_set_filter\fR() +T} +.TE +.P +In particular, notice that the operations normally used by a trace +analyzer process, such as +\fIposix_trace_rewind\fR() +or +\fIposix_trace_close\fR(), +cannot be invoked using the trace stream identifier returned by the +\fIposix_trace_create\fR() +function. +.P +A trace stream shall be created in a suspended state. +If the Trace Event Filter option is supported, its trace event type +filter shall be empty. +.P +The +\fIposix_trace_create\fR() +function may be called multiple times from the same or different +processes, with the system-wide limit indicated by the runtime +invariant value +{TRACE_SYS_MAX}, +which has the minimum value +{_POSIX_TRACE_SYS_MAX}. +.P +The trace stream identifier returned by the +\fIposix_trace_create\fR() +function in the argument pointed to by +.IR trid +is valid only in the process that made the function call. If it is +used from another process, that is a child process, in functions +defined in POSIX.1\(hy2008, these functions shall return with the error +.BR [EINVAL] . +.P +The +\fIposix_trace_create_withlog\fR() +function shall be equivalent to +\fIposix_trace_create\fR(), +except that it associates a trace log with this stream. The +.IR file_desc +argument shall be the file descriptor designating the trace log +destination. The function shall fail if this file descriptor refers to +a file with a file type that is not compatible with the log policy +associated with the trace log. The list of the appropriate file types +that are compatible with each log policy is implementation-defined. +.P +The +\fIposix_trace_create_withlog\fR() +function shall return in the parameter pointed to by +.IR trid +the trace stream identifier, which uniquely identifies the newly +created trace stream, and shall be used in subsequent calls to control +tracing. The +.IR trid +argument may only be used by the following functions: +.TS +tab(!); +l l. +T{ +.nf +\fIposix_trace_clear\fR() +\fIposix_trace_eventid_equal\fR() +\fIposix_trace_eventid_get_name\fR() +\fIposix_trace_eventtypelist_getnext_id\fR() +\fIposix_trace_eventtypelist_rewind\fR() +\fIposix_trace_flush\fR() +\fIposix_trace_get_attr\fR() +T}!T{ +.nf +\fIposix_trace_get_status\fR() +\fIposix_trace_getnext_event\fR() +\fIposix_trace_shutdown\fR() +\fIposix_trace_start\fR() +\fIposix_trace_stop\fR() +\fIposix_trace_timedgetnext_event\fR() +\fIposix_trace_trid_eventid_open\fR() +.fi +T} +.TE +.P +If the Trace Event Filter option is supported, the following additional +functions may use the +.IR trid +argument: +.TS +tab(!); +l l. +T{ +\fIposix_trace_get_filter\fR() +T}!T{ +\fIposix_trace_set_filter\fR() +T} +.TE +.P +In particular, notice that the operations normally used by a trace +analyzer process, such as +\fIposix_trace_rewind\fR() +or +\fIposix_trace_close\fR(), +cannot be invoked using the trace stream identifier returned by the +\fIposix_trace_create_withlog\fR() +function. +.P +The +\fIposix_trace_flush\fR() +function shall initiate a flush operation which copies the contents of +the trace stream identified by the argument +.IR trid +into the trace log associated with the trace stream at the creation +time. If no trace log has been associated with the trace stream +pointed to by +.IR trid , +this function shall return an error. The termination of the flush +operation can be polled by the +\fIposix_trace_get_status\fR() +function. During the flush operation, it shall be possible to trace +new trace events up to the point when the trace stream becomes full. +After flushing is completed, the space used by the flushed trace events +shall be available for tracing new trace events. +.P +If flushing the trace stream causes the resulting trace log to become +full, the trace log full policy shall be applied. If the trace +.IR log-full-policy +attribute is set, the following occurs: +.IP POSIX_TRACE_UNTIL_FULL 6 +.br +The trace events that have not yet been flushed shall be discarded. +.IP POSIX_TRACE_LOOP 6 +.br +The trace events that have not yet been flushed shall be written to the +beginning of the trace log, overwriting previous trace events stored +there. +.IP POSIX_TRACE_APPEND 6 +.br +The trace events that have not yet been flushed shall be appended to the +trace log. +.P +The +\fIposix_trace_shutdown\fR() +function shall stop the tracing of trace events in the trace stream +identified by +.IR trid , +as if +\fIposix_trace_stop\fR() +had been invoked. The +\fIposix_trace_shutdown\fR() +function shall free all the resources associated with the trace +stream. +.P +The +\fIposix_trace_shutdown\fR() +function shall not return until all the resources associated with the +trace stream have been freed. When the +\fIposix_trace_shutdown\fR() +function returns, the +.IR trid +argument becomes an invalid trace stream identifier. A call to this +function shall unconditionally deallocate the resources regardless of +whether all trace events have been retrieved by the analyzer process. +Any thread blocked on one of the +\fItrace_getnext_event\fR() +functions (which specified this +.IR trid ) +before this call is unblocked with the error +.BR [EINVAL] . +.P +If the process exits, invokes a member of the +.IR exec +family of functions, or is terminated, the trace streams that the +process had created and that have not yet been shut down, shall be +automatically shut down as if an explicit call were made to the +\fIposix_trace_shutdown\fR() +function. +.P +For an active trace stream with log, when the +\fIposix_trace_shutdown\fR() +function is called, all trace events that have not yet been flushed to +the trace log shall be flushed, as in the +\fIposix_trace_flush\fR() +function, and the trace log shall be closed. +.P +When a trace log is closed, all the information that may be retrieved +later from the trace log through the trace interface shall have been +written to the trace log. This information includes the trace +attributes, the list of trace event types (with the mapping between +trace event names and trace event type identifiers), and the trace +status. +.P +In addition, unspecified information shall be written to the trace +log to allow detection of a valid trace log during the +\fIposix_trace_open\fR() +operation. +.P +The +\fIposix_trace_shutdown\fR() +function shall not return until all trace events have been flushed. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_create\fR() +and +\fIposix_trace_create_withlog\fR() +functions store the trace stream identifier value in the object +pointed to by +.IR trid , +if successful. +.SH ERRORS +The +\fIposix_trace_create\fR() +and +\fIposix_trace_create_withlog\fR() +functions shall fail if: +.TP +.BR EAGAIN +No more trace streams can be started now. +{TRACE_SYS_MAX} +has been exceeded. +.TP +.BR EINTR +The operation was interrupted by a signal. No trace stream was +created. +.TP +.BR EINVAL +One or more of the trace parameters specified by the +.IR attr +parameter is invalid. +.TP +.BR ENOMEM +The implementation does not currently have sufficient memory to create +the trace stream with the specified parameters. +.TP +.BR EPERM +The caller does not have appropriate privileges to trace the process +specified by +.IR pid . +.TP +.BR ESRCH +The +.IR pid +argument does not refer to an existing process. +.P +The +\fIposix_trace_create_withlog\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR file_desc +argument is not a valid file descriptor open for writing. +.TP +.BR EINVAL +The +.IR file_desc +argument refers to a file with a file type that does not support the +log policy associated with the trace log. +.TP +.BR ENOSPC +No space left on device. The device corresponding to the argument +.IR file_desc +does not contain the space required to create this trace log. +.P +The +\fIposix_trace_flush\fR() +and +\fIposix_trace_shutdown\fR() +functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR trid +argument does not correspond to an active trace stream with log. +.TP +.BR EFBIG +The trace log file has attempted to exceed an implementation-defined +maximum file size. +.TP +.BR ENOSPC +No space left on device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_create\fR(), +\fIposix_trace_create_withlog\fR(), +\fIposix_trace_flush\fR(), +and +\fIposix_trace_shutdown\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_clear\fR\^(\|)", +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_eventtypelist_getnext_id\fR\^(\|)", +.IR "\fIposix_trace_get_attr\fR\^(\|)", +.IR "\fIposix_trace_get_filter\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_event.3p b/upstream/archlinux/man3p/posix_trace_event.3p new file mode 100644 index 00000000..9c29bcf4 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_event.3p @@ -0,0 +1,180 @@ +'\" et +.TH POSIX_TRACE_EVENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_event, +posix_trace_eventid_open +\(em trace functions for instrumenting application code +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +void posix_trace_event(trace_event_id_t \fIevent_id\fP, + const void *restrict \fIdata_ptr\fP, size_t \fIdata_len\fP); +int posix_trace_eventid_open(const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent_id\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_event\fR() +function shall record the +.IR event_id +and the user data pointed to by +.IR data_ptr +in the trace stream into which the calling process is being traced and +in which +.IR event_id +is not filtered out. If the total size of the user trace event data +represented by +.IR data_len +is not greater than the declared maximum size for user trace event +data, then the +.IR truncation-status +attribute of the trace event recorded is POSIX_TRACE_NOT_TRUNCATED. +Otherwise, the user trace event data is truncated to this declared +maximum size and the +.IR truncation-status +attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD. +.P +If there is no trace stream created for the process or if the created +trace stream is not running, or if the trace event specified by +.IR event_id +is filtered out in the trace stream, the +\fIposix_trace_event\fR() +function shall have no effect. +.P +The +\fIposix_trace_eventid_open\fR() +function shall associate a user trace event name with a trace +event type identifier for the calling process. The trace event name is +the string pointed to by the argument +.IR event_name . +It shall have a maximum of +{TRACE_EVENT_NAME_MAX} +characters (which has the minimum value +{_POSIX_TRACE_EVENT_NAME_MAX}). +The number of user trace event type identifiers that can be defined for +any given process is limited by the maximum value +{TRACE_USER_EVENT_MAX}, +which has the minimum value +{POSIX_TRACE_USER_EVENT_MAX}. +.P +If the Trace Inherit option is not supported, the +\fIposix_trace_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for the +traced process, and is returned in the variable pointed to by the +.IR event_id +argument. If the user trace event name has already been mapped for the +traced process, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.P +If the Trace Inherit option is supported, the +\fIposix_trace_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for all the +processes being traced in this same trace stream, and is returned in +the variable pointed to by the +.IR event_id +argument. If the user trace event name has already been mapped for the +traced processes, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (\c +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.TP 10 +.BR Note: +The above procedure, together with the fact that multiple processes can +only be traced into the same trace stream by inheritance, ensure that +all the processes that are traced into a trace stream have the same +mapping of trace event names to trace event type identifiers. +.P +.P +If there is no trace stream created, the +\fIposix_trace_eventid_open\fR() +function shall store this information for future trace streams created +for this process. +.SH "RETURN VALUE" +No return value is defined for the +\fIposix_trace_event\fR() +function. +.P +Upon successful completion, the +\fIposix_trace_eventid_open\fR() +function shall return a value of zero. Otherwise, it shall return the +corresponding error number. The +\fIposix_trace_eventid_open\fR() +function stores the trace event type identifier value in the object +pointed to by +.IR event_id , +if successful. +.SH ERRORS +The +\fIposix_trace_eventid_open\fR() +function shall fail if: +.TP +.BR ENAMETOOLONG +.br +The size of the name pointed to by the +.IR event_name +argument was longer than the implementation-defined value +{TRACE_EVENT_NAME_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_event\fR() +and +\fIposix_trace_eventid_open\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Table 2-7" ", " "Trace Option: User Trace Event", +.IR "\fIexec\fR\^", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_start\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_eventid_equal.3p b/upstream/archlinux/man3p/posix_trace_eventid_equal.3p new file mode 100644 index 00000000..c4bf5e41 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_eventid_equal.3p @@ -0,0 +1,227 @@ +'\" et +.TH POSIX_TRACE_EVENTID_EQUAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_eventid_equal, +posix_trace_eventid_get_name, +posix_trace_trid_eventid_open +\(em manipulate the trace event type identifier +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_eventid_equal(trace_id_t \fItrid\fP, trace_event_id_t \fIevent1\fP, + trace_event_id_t \fIevent2\fP); +int posix_trace_eventid_get_name(trace_id_t \fItrid\fP, + trace_event_id_t \fIevent\fP, char *\fIevent_name\fP); +int posix_trace_trid_eventid_open(trace_id_t \fItrid\fP, + const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_eventid_equal\fR() +function shall compare the trace event type identifiers +.IR event1 +and +.IR event2 +from the same trace stream or the same trace log identified by the +.IR trid +argument. If the trace event type identifiers +.IR event1 +and +.IR event2 +are from different trace streams, the return value shall be +unspecified. +.P +The +\fIposix_trace_eventid_get_name\fR() +function shall return, in the argument pointed to by +.IR event_name , +the trace event name associated with the trace event type identifier +identified by the argument +.IR event , +for the trace stream or for the trace log identified by the +.IR trid +argument. The name of the trace event shall have a maximum of +{TRACE_EVENT_NAME_MAX} +characters (which has the minimum value +{_POSIX_TRACE_EVENT_NAME_MAX}). +Successive calls to this function with the same trace event type +identifier and the same trace stream identifier shall return the same +event name. +.P +The +\fIposix_trace_trid_eventid_open\fR() +function shall associate a user trace event name with a trace +event type identifier for a given trace stream. The trace stream is +identified by the +.IR trid +argument, and it shall be an active trace stream. The trace event name +is the string pointed to by the argument +.IR event_name . +It shall have a maximum of +{TRACE_EVENT_NAME_MAX} +characters (which has the minimum value +{_POSIX_TRACE_EVENT_NAME_MAX}). +The number of user trace event type identifiers that can be defined for +any given process is limited by the maximum value +{TRACE_USER_EVENT_MAX}, +which has the minimum value +{_POSIX_TRACE_USER_EVENT_MAX}. +.P +If the Trace Inherit option is not supported, the +\fIposix_trace_trid_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for the +process being traced in the trace stream identified by the +.IR trid +argument, and is returned in the variable pointed to by the +.IR event +argument. If the user trace event name has already been mapped for the +traced process, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.P +If the Trace Inherit option is supported, the +\fIposix_trace_trid_eventid_open\fR() +function shall associate the user trace event name pointed to by the +.IR event_name +argument with a trace event type identifier that is unique for all the +processes being traced in the trace stream identified by the +.IR trid +argument, and is returned in the variable pointed to by the +.IR event +argument. If the user trace event name has already been mapped for the +traced processes, then the previously assigned trace event type +identifier shall be returned. If the per-process user trace event name +limit represented by +{TRACE_USER_EVENT_MAX} +has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see +.IR "Table 2-7" ", " "Trace Option: User Trace Event") +user trace event shall be returned. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_trace_eventid_get_name\fR() +and +\fIposix_trace_trid_eventid_open\fR() +functions shall return a value of zero. Otherwise, they shall return +the corresponding error number. +.P +The +\fIposix_trace_eventid_equal\fR() +function shall return a non-zero value if +.IR event1 +and +.IR event2 +are equal; otherwise, a value of zero shall be returned. No errors are +defined. If either +.IR event1 +or +.IR event2 +are not valid trace event type identifiers for the trace stream +specified by +.IR trid +or if the +.IR trid +is invalid, the behavior shall be unspecified. +.P +The +\fIposix_trace_eventid_get_name\fR() +function stores the trace event name value in the object pointed to by +.IR event_name , +if successful. +.P +The +\fIposix_trace_trid_eventid_open\fR() +function stores the trace event type identifier value in the object +pointed to by +.IR event , +if successful. +.SH ERRORS +The +\fIposix_trace_eventid_get_name\fR() +and +\fIposix_trace_trid_eventid_open\fR() +functions shall fail if: +.TP +.BR EINVAL +The +.IR trid +argument was not a valid trace stream identifier. +.P +The +\fIposix_trace_trid_eventid_open\fR() +function shall fail if: +.TP +.BR ENAMETOOLONG +.br +The size of the name pointed to by the +.IR event_name +argument was longer than the implementation-defined value +{TRACE_EVENT_NAME_MAX}. +.P +The +\fIposix_trace_eventid_get_name\fR() +function shall fail if: +.TP +.BR EINVAL +The trace event type identifier +.IR event +was not associated with any name. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_eventid_equal\fR(), +\fIposix_trace_eventid_get_name\fR(), +and +\fIposix_trace_trid_eventid_open\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "Table 2-7" ", " "Trace Option: User Trace Event", +.IR "\fIexec\fR\^", +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_eventid_open.3p b/upstream/archlinux/man3p/posix_trace_eventid_open.3p new file mode 100644 index 00000000..cbb5f3e6 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_eventid_open.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_EVENTID_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_eventid_open +\(em trace functions for instrumenting application code +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_eventid_open(const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent_id\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_event\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_eventset_add.3p b/upstream/archlinux/man3p/posix_trace_eventset_add.3p new file mode 100644 index 00000000..8ff35eef --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_eventset_add.3p @@ -0,0 +1,157 @@ +'\" et +.TH POSIX_TRACE_EVENTSET_ADD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +.ad l +posix_trace_eventset_add, +posix_trace_eventset_del, +posix_trace_eventset_empty, +posix_trace_eventset_fill, +posix_trace_eventset_ismember +\(em manipulate trace event type sets +(\fBTRACING\fP) +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_eventset_add(trace_event_id_t \fIevent_id\fP, + trace_event_set_t *\fIset\fP); +int posix_trace_eventset_del(trace_event_id_t \fIevent_id\fP, + trace_event_set_t *\fIset\fP); +int posix_trace_eventset_empty(trace_event_set_t *\fIset\fP); +int posix_trace_eventset_fill(trace_event_set_t *\fIset\fP, int \fIwhat\fP); +int posix_trace_eventset_ismember(trace_event_id_t \fIevent_id\fP, + const trace_event_set_t *restrict \fIset\fP, int *restrict \fIismember\fP); +.fi +.SH DESCRIPTION +These primitives manipulate sets of trace event types. They operate on +data objects addressable by the application, not on the current trace +event filter of any trace stream. +.P +The +\fIposix_trace_eventset_add\fR() +and +\fIposix_trace_eventset_del\fR() +functions, respectively, shall add or delete the individual trace event +type specified by the value of the argument +.IR event_id +to or from the trace event type set pointed to by the argument +.IR set . +Adding a trace event type already in the set or deleting a trace event +type not in the set shall not be considered an error. +.P +The +\fIposix_trace_eventset_empty\fR() +function shall initialize the trace event type set pointed to by the +.IR set +argument such that all trace event types defined, both system and user, +shall be excluded from the set. +.P +The +\fIposix_trace_eventset_fill\fR() +function shall initialize the trace event type set pointed to by the +argument +.IR set , +such that the set of trace event types defined by the argument +.IR what +shall be included in the set. The value of the argument +.IR what +shall consist of one of the following values, as defined in the +.IR +header: +.IP POSIX_TRACE_WOPID_EVENTS 6 +.br +All the process-independent implementation-defined system trace event +types are included in the set. +.IP POSIX_TRACE_SYSTEM_EVENTS 6 +.br +All the implementation-defined system trace event types are included in +the set, as are those defined in POSIX.1\(hy2008. +.IP POSIX_TRACE_ALL_EVENTS 6 +.br +All trace event types defined, both system and user, are included in +the set. +.P +Applications shall call either +\fIposix_trace_eventset_empty\fR() +or +\fIposix_trace_eventset_fill\fR() +at least once for each object of type +.BR trace_event_set_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of the +\fIposix_trace_eventset_add\fR(), +\fIposix_trace_eventset_del\fR(), +or +\fIposix_trace_eventset_ismember\fR() +functions, the results are undefined. +.P +The +\fIposix_trace_eventset_ismember\fR() +function shall test whether the trace event type specified by the value +of the argument +.IR event_id +is a member of the set pointed to by the argument +.IR set . +The value returned in the object pointed to by +.IR ismember +argument is zero if the trace event type identifier is not a member of +the set and a value different from zero if it is a member of the set. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value of one of the arguments is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_eventset_add\fR(), +\fIposix_trace_eventset_del\fR(), +\fIposix_trace_eventset_empty\fR(), +\fIposix_trace_eventset_fill\fR(), +and +\fIposix_trace_eventset_ismember\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_get_filter\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_eventtypelist_getnext_id.3p b/upstream/archlinux/man3p/posix_trace_eventtypelist_getnext_id.3p new file mode 100644 index 00000000..d58ecdf4 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_eventtypelist_getnext_id.3p @@ -0,0 +1,111 @@ +'\" et +.TH POSIX_TRACE_EVENTTYPELIST_GETNEXT_ID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_eventtypelist_getnext_id, +posix_trace_eventtypelist_rewind +\(em iterate over a mapping of trace event types +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_eventtypelist_getnext_id(trace_id_t \fItrid\fP, + trace_event_id_t *restrict \fIevent\fP, int *restrict \fIunavailable\fP); +int posix_trace_eventtypelist_rewind(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The first time +\fIposix_trace_eventtypelist_getnext_id\fR() +is called, the function shall return in the variable pointed to by +.IR event +the first trace event type identifier of the list of trace events of +the trace stream identified by the +.IR trid +argument. Successive calls to +\fIposix_trace_eventtypelist_getnext_id\fR() +return in the variable pointed to by +.IR event +the next trace event type identifier in that same list. Each time a +trace event type identifier is successfully written into the variable +pointed to by the +.IR event +argument, the variable pointed to by the +.IR unavailable +argument shall be set to zero. When no more trace event type +identifiers are available, and so none is returned, the variable +pointed to by the +.IR unavailable +argument shall be set to a value different from zero. +.P +The +\fIposix_trace_eventtypelist_rewind\fR() +function shall reset the next trace event type identifier to be read to +the first trace event type identifier from the list of trace events +used in the trace stream identified by +.IR trid . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_eventtypelist_getnext_id\fR() +function stores the trace event type identifier value in the object +pointed to by +.IR event , +if successful. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The +.IR trid +argument was not a valid trace stream identifier. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_eventtypelist_getnext_id\fR() +and +\fIposix_trace_eventtypelist_rewind\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_event\fR\^(\|)", +.IR "\fIposix_trace_eventid_equal\fR\^(\|)", +.IR "\fIposix_trace_getnext_event\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_flush.3p b/upstream/archlinux/man3p/posix_trace_flush.3p new file mode 100644 index 00000000..8628000a --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_flush.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_FLUSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_flush +\(em trace stream flush from a process +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_flush(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_create\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_get_attr.3p b/upstream/archlinux/man3p/posix_trace_get_attr.3p new file mode 100644 index 00000000..2ab75037 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_get_attr.3p @@ -0,0 +1,140 @@ +'\" et +.TH POSIX_TRACE_GET_ATTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_get_attr, +posix_trace_get_status +\(em retrieve the trace attributes or trace status +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_get_attr(trace_id_t \fItrid\fP, trace_attr_t *\fIattr\fP); +int posix_trace_get_status(trace_id_t \fItrid\fP, + struct posix_trace_status_info *\fIstatusinfo\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_get_attr\fR() +function shall copy the attributes of the active trace stream +identified by +.IR trid +into the object pointed to by the +.IR attr +argument. +If the Trace Log option is supported, +.IR trid +may represent a pre-recorded trace log. +.P +The +\fIposix_trace_get_status\fR() +function shall return, in the structure pointed to by the +.IR statusinfo +argument, the current trace status for the trace stream identified by +the +.IR trid +argument. These status values returned in the structure pointed to by +.IR statusinfo +shall have been appropriately read to ensure that the returned values +are consistent. +If the Trace Log option is supported and the +.IR trid +argument refers to a pre-recorded trace stream, the status shall be the +status of the completed trace stream. +.P +Each time the +\fIposix_trace_get_status\fR() +function is used, the overrun status of the trace stream shall be reset +to POSIX_TRACE_NO_OVERRUN +immediately after the call completes. +If the Trace Log option is supported, the +\fIposix_trace_get_status\fR() +function shall behave the same as when the option is not supported +except for the following differences: +.IP " *" 4 +If the +.IR trid +argument refers to a trace stream with log, each time the +\fIposix_trace_get_status\fR() +function is used, the log overrun status of the trace stream shall be +reset to POSIX_TRACE_NO_OVERRUN and the +.IR flush_error +status shall be reset to zero immediately after the call completes. +.IP " *" 4 +If the +.IR trid +argument refers to a pre-recorded trace stream, the status returned +shall be the status of the completed trace stream and the status values +of the trace stream shall not be reset. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_get_attr\fR() +function stores the trace attributes in the object pointed to by +.IR attr , +if successful. +.P +The +\fIposix_trace_get_status\fR() +function stores the trace status in the object pointed to by +.IR statusinfo , +if successful. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The trace stream argument +.IR trid +does not correspond to a valid active trace stream or a valid trace +log. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_get_attr\fR() +and +\fIposix_trace_get_status\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "\fIposix_trace_attr_destroy\fR\^(\|)", +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_get_filter.3p b/upstream/archlinux/man3p/posix_trace_get_filter.3p new file mode 100644 index 00000000..f494ee30 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_get_filter.3p @@ -0,0 +1,145 @@ +'\" et +.TH POSIX_TRACE_GET_FILTER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_get_filter, +posix_trace_set_filter +\(em retrieve and set the filter of an initialized trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_get_filter(trace_id_t \fItrid\fP, trace_event_set_t *\fIset\fP); +int posix_trace_set_filter(trace_id_t \fItrid\fP, + const trace_event_set_t *\fIset\fP, int \fIhow\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_get_filter\fR() +function shall retrieve, into the argument pointed to by +.IR set , +the actual trace event filter from the trace stream specified by +.IR trid . +.P +The +\fIposix_trace_set_filter\fR() +function shall change the set of filtered trace event types after a +trace stream identified by the +.IR trid +argument is created. This function may be called prior to starting the +trace stream, or while the trace stream is active. By default, if no +call is made to +\fIposix_trace_set_filter\fR(), +all trace events shall be recorded (that is, none of the trace event +types are filtered out). +.P +If this function is called while the trace is in progress, a special +system trace event, POSIX_TRACE_FILTER, +shall be recorded in the trace indicating both the old and the new sets +of filtered trace event types (see +.IR "Table 2-4" ", " "Trace and Trace Event Filter Options: System Trace Events" +and +.IR "Table 2-6" ", " "Trace" ", " "Trace Log" ", " "and Trace Event Filter Options: System Trace Events"). +.P +If the +\fIposix_trace_set_filter\fR() +function is interrupted by a signal, an error shall be returned and the +filter shall not be changed. In this case, the state of the trace +stream shall not be changed. +.P +The value of the argument +.IR how +indicates the manner in which the set is to be changed and shall have +one of the following values, as defined in the +.IR +header: +.IP POSIX_TRACE_SET_EVENTSET 6 +.br +The resulting set of trace event types to be filtered shall be the +trace event type set pointed to by the argument +.IR set . +.IP POSIX_TRACE_ADD_EVENTSET 6 +.br +The resulting set of trace event types to be filtered shall be the +union of the current set and the trace event type set pointed to by the +argument +.IR set . +.IP POSIX_TRACE_SUB_EVENTSET 6 +.br +The resulting set of trace event types to be filtered shall be all +trace event types in the current set that are not in the set pointed to +by the argument +.IR set ; +that is, remove each element of the specified set from the current +filter. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +The +\fIposix_trace_get_filter\fR() +function stores the set of filtered trace event types in +.IR set , +if successful. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR trid +argument does not correspond to an active trace stream or the value of +the argument pointed to by +.IR set +is invalid. +.TP +.BR EINTR +The operation was interrupted by a signal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_get_filter\fR() +and +\fIposix_trace_set_filter\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.ad l +.IR "Table 2-4" ", " "Trace and Trace Event Filter Options: System Trace Events", +.IR "Table 2-6" ", " "Trace" ", " "Trace Log" ", " "and Trace Event Filter Options: System Trace Events", +.IR "\fIposix_trace_eventset_add\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_get_status.3p b/upstream/archlinux/man3p/posix_trace_get_status.3p new file mode 100644 index 00000000..3067bf3b --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_get_status.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_GET_STATUS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_get_status +\(em retrieve the trace status +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_get_status(trace_id_t \fItrid\fP, + struct posix_trace_status_info *\fIstatusinfo\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_get_attr\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_getnext_event.3p b/upstream/archlinux/man3p/posix_trace_getnext_event.3p new file mode 100644 index 00000000..475f549a --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_getnext_event.3p @@ -0,0 +1,267 @@ +'\" et +.TH POSIX_TRACE_GETNEXT_EVENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_getnext_event, +posix_trace_timedgetnext_event, +posix_trace_trygetnext_event +\(em retrieve a trace event +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_getnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP); +int posix_trace_timedgetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP, + const struct timespec *restrict \fIabstime\fP); +int posix_trace_trygetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_getnext_event\fR() +function shall report a recorded trace event either from an +active trace stream without log +or a pre-recorded trace stream identified by the +.IR trid +argument. +The +\fIposix_trace_trygetnext_event\fR() +function shall report a recorded trace event from an active +trace stream without log identified by the +.IR trid +argument. +.P +The trace event information associated with the recorded trace event +shall be copied by the function into the structure pointed to by the +argument +.IR event +and the data associated with the trace event shall be copied into the +buffer pointed to by the +.IR data +argument. +.P +The +\fIposix_trace_getnext_event\fR() +function shall block if the +.IR trid +argument identifies an active trace stream and there is currently no +trace event ready to be retrieved. When returning, if a recorded trace +event was reported, the variable pointed to by the +.IR unavailable +argument shall be set to zero. Otherwise, the variable pointed to by +the +.IR unavailable +argument shall be set to a value different from zero. +.P +The +\fIposix_trace_timedgetnext_event\fR() +function shall attempt to get another trace event from an active trace +stream without log, as in the +\fIposix_trace_getnext_event\fR() +function. However, if no trace event is available from the trace +stream, the implied wait shall be terminated when the timeout specified +by the argument +.IR abstime +expires, and the function shall return the error +.BR [ETIMEDOUT] . +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock upon which timeouts are based (that +is, when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock +on which it is based. The +.BR timespec +data type is defined in the +.IR +header. +.P +Under no circumstance shall the function fail with a timeout if a trace +event is immediately available from the trace stream. The validity of +the +.IR abstime +argument need not be checked if a trace event is immediately available +from the trace stream. +.P +The behavior of this function for a pre-recorded trace stream is +unspecified. +.P +The +\fIposix_trace_trygetnext_event\fR() +function shall not block. +This function shall return an error if the +.IR trid +argument identifies a pre-recorded trace stream. +If a recorded trace event was reported, the variable pointed to by the +.IR unavailable +argument shall be set to zero. Otherwise, if no trace event was +reported, the variable pointed to by the +.IR unavailable +argument shall be set to a value different from zero. +.P +The argument +.IR num_bytes +shall be the size of the buffer pointed to by the +.IR data +argument. The argument +.IR data_len +reports to the application the length in bytes of the data record just +transferred. If +.IR num_bytes +is greater than or equal to the size of the data associated with the +trace event pointed to by the +.IR event +argument, all the recorded data shall be transferred. In this case, +the +.IR truncation-status +member of the trace event structure shall be either +POSIX_TRACE_NOT_TRUNCATED, +if the trace event data was recorded without truncation while tracing, +or POSIX_TRACE_TRUNCATED_RECORD, +if the trace event data was truncated when it was recorded. If the +.IR num_bytes +argument is less than the length of recorded trace event data, the data +transferred shall be truncated to a length of +.IR num_bytes , +the value stored in the variable pointed to by +.IR data_len +shall be equal to +.IR num_bytes , +and the +.IR truncation-status +member of the +.IR event +structure argument shall be set to POSIX_TRACE_TRUNCATED_READ +(see the +.BR posix_trace_event_info +structure defined in +.IR ). +.P +The report of a trace event shall be sequential starting from the +oldest recorded trace event. Trace events shall be reported in the +order in which they were generated, up to an implementation-defined +time resolution that causes the ordering of trace events occurring very +close to each other to be unknown. Once reported, a trace event cannot +be reported again from an active trace stream. Once a trace event is +reported from an active trace stream without log, the trace stream +shall make the resources associated with that trace event available to +record future generated trace events. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.P +If successful, these functions store: +.IP " *" 4 +The recorded trace event in the object pointed to by +.IR event +.IP " *" 4 +The trace event information associated with the recorded trace event in +the object pointed to by +.IR data +.IP " *" 4 +The length of this trace event information in the object pointed to by +.IR data_len +.IP " *" 4 +The value of zero in the object pointed to by +.IR unavailable +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The trace stream identifier argument +.IR trid +is invalid. +.P +The +\fIposix_trace_getnext_event\fR() +and +\fIposix_trace_timedgetnext_event\fR() +functions shall fail if: +.TP +.BR EINTR +The operation was interrupted by a signal, and so the call had no +effect. +.P +The +\fIposix_trace_trygetnext_event\fR() +function shall fail if: +.TP +.BR EINVAL +The trace stream identifier argument +.IR trid +does not correspond to an active trace stream. +.br +.P +The +\fIposix_trace_timedgetnext_event\fR() +function shall fail if: +.TP +.BR EINVAL +There is no trace event immediately available from the trace stream, +and the +.IR timeout +argument is invalid. +.TP +.BR ETIMEDOUT +No trace event was available from the trace stream before the specified +timeout +.IR timeout +expired. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_close\fR\^(\|)", +.IR "\fIposix_trace_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_open.3p b/upstream/archlinux/man3p/posix_trace_open.3p new file mode 100644 index 00000000..61eefd88 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_open.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_open, +posix_trace_rewind +\(em trace log management +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_open(int \fIfile_desc\fP, trace_id_t *\fItrid\fP); +int posix_trace_rewind(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_close\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_set_filter.3p b/upstream/archlinux/man3p/posix_trace_set_filter.3p new file mode 100644 index 00000000..c95eaf84 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_set_filter.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_SET_FILTER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_set_filter +\(em set filter of an initialized trace stream +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_set_filter(trace_id_t \fItrid\fP, + const trace_event_set_t *\fIset\fP, int \fIhow\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_get_filter\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_shutdown.3p b/upstream/archlinux/man3p/posix_trace_shutdown.3p new file mode 100644 index 00000000..c6e81641 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_shutdown.3p @@ -0,0 +1,42 @@ +'\" et +.TH POSIX_TRACE_SHUTDOWN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_shutdown +\(em trace stream shutdown from a process +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_shutdown(trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_create\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_start.3p b/upstream/archlinux/man3p/posix_trace_start.3p new file mode 100644 index 00000000..212358c2 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_start.3p @@ -0,0 +1,105 @@ +'\" et +.TH POSIX_TRACE_START "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_start, +posix_trace_stop +\(em trace start and stop +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_start(trace_id_t \fItrid\fP); +int posix_trace_stop (trace_id_t \fItrid\fP); +.fi +.SH DESCRIPTION +The +\fIposix_trace_start\fR() +and +\fIposix_trace_stop\fR() +functions, respectively, shall start and stop the trace stream +identified by the argument +.IR trid . +.P +The effect of calling the +\fIposix_trace_start\fR() +function shall be recorded in the trace stream as the POSIX_TRACE_START +system trace event and the status of the trace stream shall become +POSIX_TRACE_RUNNING. +If the trace stream is in progress when this function is called, the +POSIX_TRACE_START +system trace event shall not be recorded and the trace stream shall +continue to run. If the trace stream is full, the POSIX_TRACE_START +system trace event shall not be recorded and the status of the trace +stream shall not be changed. +.P +The effect of calling the +\fIposix_trace_stop\fR() +function shall be recorded in the trace stream as the POSIX_TRACE_STOP +system trace event and the status of the trace stream shall become +POSIX_TRACE_SUSPENDED. +If the trace stream is suspended when this function is called, the +POSIX_TRACE_STOP system trace event shall not be recorded and the trace +stream shall remain suspended. If the trace stream is full, the +POSIX_TRACE_STOP system trace event shall not be recorded and the +status of the trace stream shall not be changed. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of +zero. Otherwise, they shall return the corresponding error number. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of the argument +.IR trid +does not correspond to an active trace stream and thus no trace stream +was started or stopped. +.TP +.BR EINTR +The operation was interrupted by a signal and thus the trace stream was +not necessarily started or stopped. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIposix_trace_start\fR() +and +\fIposix_trace_stop\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIposix_trace_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_timedgetnext_event.3p b/upstream/archlinux/man3p/posix_trace_timedgetnext_event.3p new file mode 100644 index 00000000..ecf702a2 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_timedgetnext_event.3p @@ -0,0 +1,46 @@ +'\" et +.TH POSIX_TRACE_TIMEDGETNEXT_EVENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_timedgetnext_event +\(em retrieve a trace event +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_timedgetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_getnext_event\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_trid_eventid_open.3p b/upstream/archlinux/man3p/posix_trace_trid_eventid_open.3p new file mode 100644 index 00000000..d6c52363 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_trid_eventid_open.3p @@ -0,0 +1,43 @@ +'\" et +.TH POSIX_TRACE_TRID_EVENTID_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_trid_eventid_open +\(em open a trace event type identifier +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_trace_trid_eventid_open(trace_id_t \fItrid\fP, + const char *restrict \fIevent_name\fP, + trace_event_id_t *restrict \fIevent\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_eventid_equal\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_trace_trygetnext_event.3p b/upstream/archlinux/man3p/posix_trace_trygetnext_event.3p new file mode 100644 index 00000000..fea6c03e --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_trygetnext_event.3p @@ -0,0 +1,45 @@ +'\" et +.TH POSIX_TRACE_TRYGETNEXT_EVENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_trace_trygetnext_event +\(em retrieve a trace event +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int posix_trace_trygetnext_event(trace_id_t \fItrid\fP, + struct posix_trace_event_info *restrict \fIevent\fP, + void *restrict \fIdata\fP, size_t \fInum_bytes\fP, + size_t *restrict \fIdata_len\fP, int *restrict \fIunavailable\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIposix_trace_getnext_event\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_typed_mem_get_info.3p b/upstream/archlinux/man3p/posix_typed_mem_get_info.3p new file mode 100644 index 00000000..be191fea --- /dev/null +++ b/upstream/archlinux/man3p/posix_typed_mem_get_info.3p @@ -0,0 +1,144 @@ +'\" et +.TH POSIX_TYPED_MEM_GET_INFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_typed_mem_get_info +\(em query typed memory information +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_typed_mem_get_info(int \fIfildes\fP, + struct posix_typed_mem_info *\fIinfo\fP); +.fi +.SH DESCRIPTION +The +\fIposix_typed_mem_get_info\fR() +function shall return, in the +.IR posix_tmi_length +field of the +.BR posix_typed_mem_info +structure pointed to by +.IR info , +the maximum length which may be successfully allocated by the typed +memory object designated by +.IR fildes . +This maximum length shall take into account the flag +POSIX_TYPED_MEM_ALLOCATE or POSIX_TYPED_MEM_ALLOCATE_CONTIG specified +when the typed memory object represented by +.IR fildes +was opened. The maximum length is dynamic; therefore, the value +returned is valid only while the current mapping of the corresponding +typed memory pool remains unchanged. +.P +If +.IR fildes +represents a typed memory object opened with neither the +POSIX_TYPED_MEM_ALLOCATE flag nor the POSIX_TYPED_MEM_ALLOCATE_CONTIG +flag specified, the returned value of \fIinfo\fR->\fIposix_tmi_length\fR +is unspecified. +.P +The +\fIposix_typed_mem_get_info\fR() +function may return additional implementation-defined information in +other fields of the +.BR posix_typed_mem_info +structure pointed to by +.IR info . +.P +If the memory object specified by +.IR fildes +is not a typed memory object, then the behavior of this function is +undefined. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_typed_mem_get_info\fR() +function shall return zero; otherwise, the corresponding error status +value shall be returned. +.SH ERRORS +The +\fIposix_typed_mem_get_info\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid open file descriptor. +.TP +.BR ENODEV +The +.IR fildes +argument is not connected to a memory object supported by this +function. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +An application that needs to allocate a block of typed memory with +length dependent upon the amount of memory currently available must +either query the typed memory object to obtain the amount available, or +repeatedly invoke +\fImmap\fR() +attempting to guess an appropriate length. While the latter method is +existing practice with +\fImalloc\fR(), +it is awkward and imprecise. The +\fIposix_typed_mem_get_info\fR() +function allows an application to immediately determine available +memory. This is particularly important for typed memory objects that +may in some cases be scarce resources. Note that when a typed memory +pool is a shared resource, some form of mutual-exclusion or +synchronization may be required while typed memory is being queried and +allocated to prevent race conditions. +.P +The existing +\fIfstat\fR() +function is not suitable for this purpose. We realize that +implementations may wish to provide other attributes of typed memory +objects (for example, alignment requirements, page size, and so on). +The +\fIfstat\fR() +function returns a structure which is not extensible and, furthermore, +contains substantial information that is inappropriate for typed memory +objects. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfstat\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIposix_typed_mem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/posix_typed_mem_open.3p b/upstream/archlinux/man3p/posix_typed_mem_open.3p new file mode 100644 index 00000000..114ec663 --- /dev/null +++ b/upstream/archlinux/man3p/posix_typed_mem_open.3p @@ -0,0 +1,279 @@ +'\" et +.TH POSIX_TYPED_MEM_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +posix_typed_mem_open +\(em open a typed memory object +(\fBADVANCED REALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int posix_typed_mem_open(const char *\fIname\fP, int \fIoflag\fP, int \fItflag\fP); +.fi +.SH DESCRIPTION +The +\fIposix_typed_mem_open\fR() +function shall establish a connection between the typed memory object +specified by the string pointed to by +.IR name +and a file descriptor. It shall create an open file description that +refers to the typed memory object and a file descriptor that refers to +that open file description. The file descriptor shall be allocated as +described in +.IR "Section 2.14" ", " "File Descriptor Allocation" +and can be used by other functions to refer to that typed +memory object. It is unspecified whether the name appears in +the file system and is visible to other functions that take +pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except that +the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as the +pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fIposix_typed_mem_open\fR() +with the same value of +.IR name +shall refer to the same typed memory object. If +.IR name +does not begin with the + +character, the effect is implementation-defined. +.P +Each typed memory object supported in a system shall be identified by a name +which specifies not only its associated typed memory pool, but also the +path or port by which it is accessed. That is, the same typed memory +pool accessed via several different ports shall have several different +corresponding names. The binding between names and typed memory objects +is established in an implementation-defined manner. Unlike shared +memory objects, there is no way within POSIX.1\(hy2008 for a program to create a +typed memory object. +.P +The value of +.IR tflag +shall determine how the typed memory object behaves when subsequently +mapped by calls to +\fImmap\fR(). +At most, one of the following flags defined in +.IR +may be specified: +.IP POSIX_TYPED_MEM_ALLOCATE 6 +.br +Allocate on +\fImmap\fR(). +.IP POSIX_TYPED_MEM_ALLOCATE_CONTIG 6 +.br +Allocate contiguously on +\fImmap\fR(). +.IP POSIX_TYPED_MEM_MAP_ALLOCATABLE 6 +.br +Map on +\fImmap\fR(), +without affecting allocatability. +.P +If +.IR tflag +has the flag POSIX_TYPED_MEM_ALLOCATE specified, any subsequent call to +\fImmap\fR() +using the returned file descriptor shall result in allocation and +mapping of typed memory from the specified typed memory pool. The +allocated memory may be a contiguous previously unallocated area of the +typed memory pool or several non-contiguous previously unallocated +areas (mapped to a contiguous portion of the process address space). If +.IR tflag +has the flag POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent +call to +\fImmap\fR() +using the returned file descriptor shall result in allocation and +mapping of a single contiguous previously unallocated area of the typed +memory pool (also mapped to a contiguous portion of the process address +space). If +.IR tflag +has none of the flags POSIX_TYPED_MEM_ALLOCATE or +POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent call to +\fImmap\fR() +using the returned file descriptor shall map an application-chosen area +from the specified typed memory pool such that this mapped area becomes +unavailable for allocation until unmapped by all processes. If +.IR tflag +has the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE specified, any subsequent +call to +\fImmap\fR() +using the returned file descriptor shall map an application-chosen area +from the specified typed memory pool without an effect on the +availability of that area for allocation; that is, mapping such an +object leaves each byte of the mapped area unallocated if it was +unallocated prior to the mapping or allocated if it was allocated prior +to the mapping. Appropriate privileges to specify the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag are implementation-defined. +.P +If successful, +\fIposix_typed_mem_open\fR() +shall return a file descriptor for the typed memory object. +The open file description is new, and therefore the file descriptor +shall not share it with any other processes. It is unspecified whether +the file offset is set. The FD_CLOEXEC file descriptor flag associated +with the new file descriptor shall be cleared. +.P +The behavior of +\fImsync\fR(), +\fIftruncate\fR(), +and all file operations other than +\fImmap\fR(), +\fIposix_mem_offset\fR(), +\fIposix_typed_mem_get_info\fR(), +\fIfstat\fR(), +\fIdup\fR(), +\fIdup2\fR(), +and +\fIclose\fR(), +is unspecified when passed a file descriptor connected to a typed +memory object by this function. +.P +The file status flags of the open file description shall be set +according to the value of +.IR oflag . +Applications shall specify exactly one of the three access mode values +described below and defined in the +.IR +header, as the value of +.IR oflag . +.IP O_RDONLY 12 +Open for read access only. +.IP O_WRONLY 12 +Open for write access only. +.IP O_RDWR 12 +Open for read or write access. +.SH "RETURN VALUE" +Upon successful completion, the +\fIposix_typed_mem_open\fR() +function shall return a non-negative integer representing the +file descriptor. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIposix_typed_mem_open\fR() +function shall fail if: +.TP +.BR EACCES +The typed memory object exists and the permissions specified by +.IR oflag +are denied. +.TP +.BR EINTR +The +\fIposix_typed_mem_open\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +.ad l +The flags specified in +.IR tflag +are invalid (more than one of POSIX_TYPED_MEM_ALLOCATE, +POSIX_TYPED_MEM_ALLOCATE_CONTIG, or POSIX_TYPED_MEM_MAP_ALLOCATABLE is +specified). +.ad b +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +Too many file descriptors are currently open in the system. +.TP +.BR ENOENT +The named typed memory object does not exist. +.TP +.BR EPERM +The caller lacks appropriate privileges to specify the +POSIX_TYPED_MEM_MAP_ALLOCATABLE flag in the +.IR tflag +argument. +.P +The +\fIposix_typed_mem_open\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "File Descriptor Allocation", +.IR "\fIclose\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIfstat\fR\^(\|)", +.IR "\fIftruncate\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fImsync\fR\^(\|)", +.IR "\fIposix_mem_offset\fR\^(\|)", +.IR "\fIposix_typed_mem_get_info\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pow.3p b/upstream/archlinux/man3p/pow.3p new file mode 100644 index 00000000..1e281259 --- /dev/null +++ b/upstream/archlinux/man3p/pow.3p @@ -0,0 +1,317 @@ +'\" et +.TH POW "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pow, +powf, +powl +\(em power function +.SH SYNOPSIS +.LP +.nf +#include +.P +double pow(double \fIx\fP, double \fIy\fP); +float powf(float \fIx\fP, float \fIy\fP); +long double powl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the value of +.IR x +raised to the power +.IR y , +.IR x\u\s-3y\s+3\d . +If +.IR x +is negative, the application shall ensure that +.IR y +is an integer value. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the value of +.IR x +raised to the power +.IR y . +.P +For finite values of +.IR x +< 0, and finite non-integer values of +.IR y , +a domain error shall occur and +either a NaN (if representable), or +an implementation-defined value shall be returned. +.P +If the correct value would cause overflow, a range error shall occur +and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +For +.IR y +< 0, if +.IR x +is zero, a +pole +error may occur and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, respectively. +On systems that support the IEC 60559 Floating-Point option, if +.IR x +is \(+-0, a pole error shall occur and +\fIpow\fR(), +\fIpowf\fR(), +and +\fIpowl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, respectively +if +.IR y +is an odd integer, or HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively if +.IR y +is not an odd integer. +.P +If +.IR x +or +.IR y +is a NaN, a NaN shall be returned (unless specified elsewhere in this +description). +.P +For any value of +.IR y +(including NaN), if +.IR x +is +1, 1.0 shall be returned. +.P +For any value of +.IR x +(including NaN), if +.IR y +is \(+-0, 1.0 shall be returned. +.P +For any odd integer value of +.IR y +> 0, if +.IR x +is \(+-0, \(+-0 shall be returned. +.P +For +.IR y +> 0 and not an odd integer, if +.IR x +is \(+-0, +0 shall be returned. +.P +If +.IR x +is \-1, and +.IR y +is \(+-Inf, 1.0 shall be returned. +.P +For |\fIx\fP| < 1, if +.IR y +is \-Inf, +Inf shall be returned. +.P +For |\fIx\fP| > 1, if +.IR y +is \-Inf, +0 shall be returned. +.P +For |\fIx\fP| < 1, if +.IR y +is +Inf, +0 shall be returned. +.P +For |\fIx\fP| > 1, if +.IR y +is +Inf, +Inf shall be returned. +.P +For +.IR y +an odd integer < 0, if +.IR x +is \-Inf, \-0 shall be returned. +.P +For +.IR y +< 0 and not an odd integer, if +.IR x +is \-Inf, +0 shall be returned. +.P +For +.IR y +an odd integer > 0, if +.IR x +is \-Inf, \-Inf shall be returned. +.P +For +.IR y +> 0 and not an odd integer, if +.IR x +is \-Inf, +Inf shall be returned. +.P +For +.IR y +< 0, if +.IR x +is +Inf, +0 shall be returned. +.P +For +.IR y +> 0, if +.IR x +is +Inf, +Inf shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is negative and +.IR y +is a finite non-integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero and +.IR y +is negative. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Pole\ Error" 12 +The value of +.IR x +is zero and +.IR y +is negative. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexp\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pread.3p b/upstream/archlinux/man3p/pread.3p new file mode 100644 index 00000000..6f847dfa --- /dev/null +++ b/upstream/archlinux/man3p/pread.3p @@ -0,0 +1,40 @@ +'\" et +.TH PREAD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pread +\(em read from a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pread(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP, off_t \fIoffset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIread\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/printf.3p b/upstream/archlinux/man3p/printf.3p new file mode 100644 index 00000000..48cef695 --- /dev/null +++ b/upstream/archlinux/man3p/printf.3p @@ -0,0 +1,40 @@ +'\" et +.TH PRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +printf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int printf(const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pselect.3p b/upstream/archlinux/man3p/pselect.3p new file mode 100644 index 00000000..5f3597d4 --- /dev/null +++ b/upstream/archlinux/man3p/pselect.3p @@ -0,0 +1,507 @@ +'\" et +.TH PSELECT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pselect, +select +\(em synchronous I/O multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +int pselect(int \fInfds\fP, fd_set *restrict \fIreadfds\fP, + fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP, + const struct timespec *restrict \fItimeout\fP, + const sigset_t *restrict \fIsigmask\fP); +int select(int \fInfds\fP, fd_set *restrict \fIreadfds\fP, + fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP, + struct timeval *restrict \fItimeout\fP); +void FD_CLR(int \fIfd\fP, fd_set *\fIfdset\fP); +int FD_ISSET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_SET(int \fIfd\fP, fd_set *\fIfdset\fP); +void FD_ZERO(fd_set *\fIfdset\fP); +.fi +.SH DESCRIPTION +The +\fIpselect\fR() +function shall examine the file descriptor sets whose addresses are +passed in the +.IR readfds , +.IR writefds , +and +.IR errorfds +parameters to see whether some of their descriptors are ready for reading, +are ready for writing, or have an exceptional condition pending, +respectively. +.P +The +\fIselect\fR() +function shall be equivalent to the +\fIpselect\fR() +function, except as follows: +.IP " *" 4 +For the +\fIselect\fR() +function, the timeout period is given in seconds and microseconds in an +argument of type +.BR "struct timeval" , +whereas for the +\fIpselect\fR() +function the timeout period is given in seconds and nanoseconds in an +argument of type +.BR "struct timespec" . +.IP " *" 4 +The +\fIselect\fR() +function has no +.IR sigmask +argument; it shall behave as +\fIpselect\fR() +does when +.IR sigmask +is a null pointer. +.IP " *" 4 +Upon successful completion, the +\fIselect\fR() +function may modify the object pointed to by the +.IR timeout +argument. +.P +The +\fIpselect\fR() +and +\fIselect\fR() +functions shall support regular files, terminal and pseudo-terminal +devices, +STREAMS-based files, +FIFOs, pipes, and sockets. The behavior of +\fIpselect\fR() +and +\fIselect\fR() +on file descriptors that refer to other types of file is unspecified. +.P +The +.IR nfds +argument specifies the range of descriptors to be tested. The first +.IR nfds +descriptors shall be checked in each set; that is, the descriptors from +zero through +.IR nfds \-1 +in the descriptor sets shall be examined. +.P +If the +.IR readfds +argument is not a null pointer, it points to an object of type +.BR fd_set +that on input specifies the file descriptors to be checked for being +ready to read, and on output indicates which file descriptors are ready +to read. +.P +If the +.IR writefds +argument is not a null pointer, it points to an object of type +.BR fd_set +that on input specifies the file descriptors to be checked for being +ready to write, and on output indicates which file descriptors are +ready to write. +.P +If the +.IR errorfds +argument is not a null pointer, it points to an object of type +.BR fd_set +that on input specifies the file descriptors to be checked for error +conditions pending, and on output indicates which file descriptors have +error conditions pending. +.P +Upon successful completion, the +\fIpselect\fR() +or +\fIselect\fR() +function shall modify the objects pointed to by the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments to indicate which file descriptors are ready for reading, +ready for writing, or have an error condition pending, respectively, +and shall return the total number of ready descriptors in all the +output sets. For each file descriptor less than +.IR nfds , +the corresponding bit shall be set upon successful completion if it +was set on input and the associated condition is true for that file +descriptor. +.P +If none of the selected descriptors are ready for the requested +operation, the +\fIpselect\fR() +or +\fIselect\fR() +function shall block until at least one of the requested operations +becomes ready, until the +.IR timeout +occurs, or until interrupted by a signal. +The +.IR timeout +parameter controls how long the +\fIpselect\fR() +or +\fIselect\fR() +function shall take before timing out. If the +.IR timeout +parameter is not a null pointer, it specifies a maximum interval to +wait for the selection to complete. If the specified time interval +expires without any requested operation becoming ready, the function +shall return. If the +.IR timeout +parameter is a null pointer, then the call to +\fIpselect\fR() +or +\fIselect\fR() +shall block indefinitely until at least one descriptor meets the +specified criteria. To effect a poll, the +.IR timeout +parameter should not be a null pointer, and should point to a +zero-valued +.BR timespec +structure. +.P +The use of a timeout does not affect any pending timers set up by +\fIalarm\fR() +or +\fIsetitimer\fR(). +.P +Implementations may place limitations on the maximum timeout interval +supported. All implementations shall support a maximum timeout interval +of at least 31 days. If the +.IR timeout +argument specifies a timeout interval greater than the +implementation-defined maximum value, the maximum value shall be used +as the actual timeout value. Implementations may also place limitations +on the granularity of timeout intervals. If the requested timeout +interval requires a finer granularity than the implementation supports, +the actual timeout interval shall be rounded up to the next supported +value. +.P +If +.IR sigmask +is not a null pointer, then the +\fIpselect\fR() +function shall replace the signal mask of the caller by the set of +signals pointed to by +.IR sigmask +before examining the descriptors, and shall restore the signal mask of +the calling thread before returning. +.P +A descriptor shall be considered ready for reading when a call to an +input function with O_NONBLOCK clear would not block, whether or not +the function would transfer data successfully. (The function might +return data, an end-of-file indication, or an error other than one +indicating that it is blocked, and in each of these cases the +descriptor shall be considered ready for reading.) +.P +A descriptor shall be considered ready for writing when a call to an +output function with O_NONBLOCK clear would not block, whether or not +the function would transfer data successfully. +.P +If a socket has a pending error, it shall be considered to have an +exceptional condition pending. Otherwise, what constitutes an +exceptional condition is file type-specific. For a file descriptor for +use with a socket, it is protocol-specific except as noted below. For +other file types it is implementation-defined. If the operation is +meaningless for a particular file type, +\fIpselect\fR() +or +\fIselect\fR() +shall indicate that the descriptor is ready for read or write +operations, and shall indicate that the descriptor has no exceptional +condition pending. +.P +If a descriptor refers to a socket, the implied input function is the +\fIrecvmsg\fR() +function with parameters requesting normal and ancillary data, such +that the presence of either type shall cause the socket to be marked as +readable. The presence of out-of-band data shall be checked if the +socket option SO_OOBINLINE has been enabled, as out-of-band data is +enqueued with normal data. If the socket is currently listening, then +it shall be marked as readable if an incoming connection request has +been received, and a call to the +\fIaccept\fR() +function shall complete without blocking. +.P +If a descriptor refers to a socket, the implied output function is the +\fIsendmsg\fR() +function supplying an amount of normal data equal to the current value +of the SO_SNDLOWAT option for the socket. If a non-blocking call to +the +\fIconnect\fR() +function has been made for a socket, and the connection attempt has +either succeeded or failed leaving a pending error, the socket shall be +marked as writable. +.P +A socket shall be considered to have an exceptional condition pending +if a receive operation with O_NONBLOCK clear for the open file +description and with the MSG_OOB flag set would return out-of-band data +without blocking. (It is protocol-specific whether the MSG_OOB flag +would be used to read out-of-band data.) A socket shall also be +considered to have an exceptional condition pending if an out-of-band +data mark is present in the receive queue. Other circumstances under +which a socket may be considered to have an exceptional condition +pending are protocol-specific and implementation-defined. +.P +If the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments are all null pointers and the +.IR timeout +argument is not a null pointer, the +\fIpselect\fR() +or +\fIselect\fR() +function shall block for the time specified, or until interrupted by +a signal. If the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments are all null pointers and the +.IR timeout +argument is a null pointer, the +\fIpselect\fR() +or +\fIselect\fR() +function shall block until interrupted by a signal. +.P +File descriptors associated with regular files shall always select true +for ready to read, ready to write, and error conditions. +.P +On failure, the objects pointed to by the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments shall not be modified. If the timeout interval expires +without the specified condition being true for any of the specified +file descriptors, the objects pointed to by the +.IR readfds , +.IR writefds , +and +.IR errorfds +arguments shall have all bits set to 0. +.P +File descriptor masks of type +.BR fd_set +can be initialized and tested with +\fIFD_CLR\fR(), +\fIFD_ISSET\fR(), +\fIFD_SET\fR(), +and +\fIFD_ZERO\fR(). +It is unspecified whether each of these is a macro or a function. If a +macro definition is suppressed in order to access an actual function, +or a program defines an external identifier with any of these names, +the behavior is undefined. +.P +\fIFD_CLR\fR(\fIfd\fR, \fIfdsetp\fR) shall remove the file descriptor +.IR fd +from the set pointed to by +.IR fdsetp . +If +.IR fd +is not a member of this set, there shall be no effect on the set, nor +will an error be returned. +.P +\fIFD_ISSET\fR(\fIfd\fR, \fIfdsetp\fR) shall evaluate to non-zero if +the file descriptor +.IR fd +is a member of the set pointed to by +.IR fdsetp , +and shall evaluate to zero otherwise. +.P +\fIFD_SET\fR(\fIfd\fR, \fIfdsetp\fR) shall add the file descriptor +.IR fd +to the set pointed to by +.IR fdsetp . +If the file descriptor +.IR fd +is already in this set, there shall be no effect on the set, nor will +an error be returned. +.P +\fIFD_ZERO\fR(\fIfdsetp\fR) shall initialize the descriptor set pointed +to by +.IR fdsetp +to the null set. No error is returned if the set is not empty at the +time +\fIFD_ZERO\fR() +is invoked. +.P +The behavior of these macros is undefined if the +.IR fd +argument is less than 0 or greater than or equal to FD_SETSIZE, or if +.IR fd +is not a valid file descriptor, or if any of the arguments are +expressions with side-effects. +.P +If a thread gets canceled during a +\fIpselect\fR() +call, the signal mask in effect when executing the registered cleanup +functions is either the original signal mask or the signal mask +installed as part of the +\fIpselect\fR() +call. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpselect\fR() +and +\fIselect\fR() +functions shall return the total number of bits set in the bit masks. +Otherwise, \-1 shall be returned, and +.IR errno +shall be set to indicate the error. +.P +\fIFD_CLR\fR(), +\fIFD_SET\fR(), +and +\fIFD_ZERO\fR() +do not return a value. +\fIFD_ISSET\fR() +shall return a non-zero value if the bit for the file descriptor +.IR fd +is set in the file descriptor set pointed to by +.IR fdset , +and 0 otherwise. +.SH ERRORS +Under the following conditions, +\fIpselect\fR() +and +\fIselect\fR() +shall fail and set +.IR errno +to: +.TP +.BR EBADF +One or more of the file descriptor sets specified a file descriptor +that is not a valid open file descriptor. +.TP +.BR EINTR +The function was interrupted while blocked waiting for any of the +selected descriptors to become ready and before the timeout interval +expired. +.RS 12 +.P +If SA_RESTART has been set for the interrupting signal, it is +implementation-defined whether the function restarts or returns with +.BR [EINTR] . +.RE +.TP +.BR EINVAL +An invalid timeout interval was specified. +.TP +.BR EINVAL +The +.IR nfds +argument is less than 0 or greater than FD_SETSIZE. +.TP +.BR EINVAL +One of the specified file descriptors refers to a STREAM or multiplexer +that is linked (directly or indirectly) downstream from a multiplexer. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +In earlier versions of the Single UNIX Specification, the +\fIselect\fR() +function was defined in the +.IR +header. This is now changed to +.IR . +The rationale for this change was as follows: the introduction of the +\fIpselect\fR() +function included the +.IR +header and the +.IR +header defines all the related definitions for the +\fIpselect\fR() +and +\fIselect\fR() +functions. Backwards-compatibility to existing XSI implementations is +handled by allowing +.IR +to include +.IR . +.P +Code which wants to avoid the ambiguity of the signal mask for thread +cancellation handlers can install an additional cancellation handler +which resets the signal mask to the expected value. +.sp +.RS 4 +.nf + +void cleanup(void *arg) +{ + sigset_t *ss = (sigset_t *) arg; + pthread_sigmask(SIG_SETMASK, ss, NULL); +} +.P +int call_pselect(int nfds, fd_set *readfds, fd_set *writefds, + fd_set errorfds, const struct timespec *timeout, + const sigset_t *sigmask) +{ + sigset_t oldmask; + int result; + pthread_sigmask(SIG_SETMASK, NULL, &oldmask); + pthread_cleanup_push(cleanup, &oldmask); + result = pselect(nfds, readfds, writefds, errorfds, timeout, sigmask); + pthread_cleanup_pop(0); + return result; +} +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIaccept\fR\^(\|)", +.IR "\fIalarm\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/psiginfo.3p b/upstream/archlinux/man3p/psiginfo.3p new file mode 100644 index 00000000..8e503832 --- /dev/null +++ b/upstream/archlinux/man3p/psiginfo.3p @@ -0,0 +1,179 @@ +'\" et +.TH PSIGINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +psiginfo, psignal +\(em write signal information to standard error +.SH SYNOPSIS +.LP +.nf +#include +.P +void psiginfo(const siginfo_t *\fIpinfo\fP, const char *\fImessage\fP); +void psignal(int \fIsignum\fP, const char *\fImessage\fP); +.fi +.SH DESCRIPTION +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall write a language-dependent message associated with a +signal number to the standard error stream as follows: +.IP " *" 4 +First, if +.IR message +is not a null pointer and is not the empty string, the string pointed +to by the +.IR message +argument shall be written, followed by a + +and a +. +.IP " *" 4 +Then the signal description string associated with +.IR signum +or with the signal indicated by +.IR pinfo +shall be written, followed by a +. +.P +For +\fIpsiginfo\fR(), +the application shall ensure that the argument +.IR pinfo +references a valid +.BR siginfo_t +structure. For +\fIpsignal\fR(), +if +.IR signum +is not a valid signal number, the behavior is implementation-defined. +.P +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall not change the orientation of the standard error stream. +.P +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall mark for update the last data modification and last file +status change timestamps of the file associated with the standard error +stream at some time between their successful completion and +\fIexit\fR(), +\fIabort\fR(), +or the completion of +\fIfflush\fR() +or +\fIfclose\fR() +on +.IR stderr . +.P +The +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +On error, the +\fIpsiginfo\fR() +and +\fIpsignal\fR() +functions shall set the error indicator for the stream to which +.IR stderr +points, and shall set +.IR errno +to indicate the error. +.P +Since no value is returned, an application wishing to check for error +situations should set +.IR errno +to 0, then call +\fIpsiginfo\fR() +or +\fIpsignal\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +These functions shall not return a value. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +As an alternative to setting +.IR errno +to zero before the call and checking if it is non-zero afterwards, +applications can use +\fIferror\fR() +to detect whether +\fIpsiginfo\fR() +or +\fIpsignal\fR() +encountered an error. +.P +An application wishing to use this method to check for error situations +should call +.IR clearerr ( stderr ) +before calling +\fIpsiginfo\fR() +or +\fIpsignal\fR(), +then if +.IR ferror ( stderr ) +returns non-zero, the value of +.IR errno +indicates which error occurred. +.SH RATIONALE +System V historically has +\fIpsignal\fR() +and +\fIpsiginfo\fR() +in +.IR . +However, the +.IR +header is not specified in the Base Definitions volume of POSIX.1\(hy2017, and the type +.BR siginfo_t +is defined in +.IR . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfputc\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIstrsignal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_atfork.3p b/upstream/archlinux/man3p/pthread_atfork.3p new file mode 100644 index 00000000..8f3f5a7f --- /dev/null +++ b/upstream/archlinux/man3p/pthread_atfork.3p @@ -0,0 +1,262 @@ +'\" et +.TH PTHREAD_ATFORK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_atfork +\(em register fork handlers +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_atfork(void (*\fIprepare\fP)(void), void (*\fIparent\fP)(void), + void (*\fIchild\fP)(void)); +.fi +.SH DESCRIPTION +The +\fIpthread_atfork\fR() +function shall declare fork handlers to be called before and after +\fIfork\fR(), +in the context of the thread that called +\fIfork\fR(). +The +.IR prepare +fork handler shall be called before +\fIfork\fR() +processing commences. The +.IR parent +fork handle shall be called after +\fIfork\fR() +processing completes in the parent process. The +.IR child +fork handler shall be called after +\fIfork\fR() +processing completes in the child process. If no handling is desired +at one or more of these three points, the corresponding fork handler +address(es) may be set to NULL. +.P +If a +\fIfork\fR() +call in a multi-threaded process leads to a +.IR child +fork handler calling any function that is not async-signal-safe, the +behavior is undefined. +.P +The order of calls to +\fIpthread_atfork\fR() +is significant. The +.IR parent +and +.IR child +fork handlers shall be called in the order in which they were +established by calls to +\fIpthread_atfork\fR(). +The +.IR prepare +fork handlers shall be called in the opposite order. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_atfork\fR() +shall return a value of zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_atfork\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient table space exists to record the fork handler addresses. +.P +The +\fIpthread_atfork\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The original usage pattern envisaged for +\fIpthread_atfork\fR() +was for the +.IR prepare +fork handler to lock mutexes and other locks, and for the +.IR parent +and +.IR child +handlers to unlock them. However, since all of the relevant unlocking +functions, except +\fIsem_post\fR(), +are not async-signal-safe, this usage results in undefined behavior in +the child process unless the only such unlocking function it calls is +\fIsem_post\fR(). +.SH RATIONALE +There are at least two serious problems with the semantics of +\fIfork\fR() +in a multi-threaded program. One problem has to do with state (for +example, memory) covered by mutexes. Consider the case where one +thread has a mutex locked and the state covered by that mutex is +inconsistent while another thread calls +\fIfork\fR(). +In the child, the mutex is in the locked state (locked by a nonexistent +thread and thus can never be unlocked). Having the child simply +reinitialize the mutex is unsatisfactory since this approach does not +resolve the question about how to correct or otherwise deal with the +inconsistent state in the child. +.P +It is suggested that programs that use +\fIfork\fR() +call an +.IR exec +function very soon afterwards in the child process, thus resetting all +states. In the meantime, only a short list of async-signal-safe +library routines are promised to be available. +.P +Unfortunately, this solution does not address the needs of +multi-threaded libraries. Application programs may not be aware that a +multi-threaded library is in use, and they feel free to call any number +of library routines between the +\fIfork\fR() +and +.IR exec +calls, just as they always have. Indeed, they may be extant +single-threaded programs and cannot, therefore, be expected to obey new +restrictions imposed by the threads library. +.P +On the other hand, the multi-threaded library needs a way to protect +its internal state during +\fIfork\fR() +in case it is re-entered later in the child process. The problem +arises especially in multi-threaded I/O libraries, which are almost +sure to be invoked between the +\fIfork\fR() +and +.IR exec +calls to effect I/O redirection. The solution may require locking +mutex variables during +\fIfork\fR(), +or it may entail simply resetting the state in the child after the +\fIfork\fR() +processing completes. +.P +The +\fIpthread_atfork\fR() +function was intended to provide multi-threaded libraries with a means +to protect themselves from innocent application programs that call +\fIfork\fR(), +and to provide multi-threaded application programs with a standard +mechanism for protecting themselves from +\fIfork\fR() +calls in a library routine or the application itself. +.P +The expected usage was that the prepare handler would acquire all mutex +locks and the other two fork handlers would release them. +.P +For example, an application could have supplied a prepare routine that +acquires the necessary mutexes the library maintains and supplied child +and parent routines that release those mutexes, thus ensuring that the +child would have got a consistent snapshot of the state of the library +(and that no mutexes would have been left stranded). This is good in +theory, but in reality not practical. Each and every mutex and lock +in the process must be located and locked. Every component of a program +including third-party components must participate and they must agree who +is responsible for which mutex or lock. This is especially problematic +for mutexes and locks in dynamically allocated memory. All mutexes and +locks internal to the implementation must be locked, too. This possibly +delays the thread calling +\fIfork\fR() +for a long time or even indefinitely since uses of these synchronization +objects may not be under control of the application. A final problem +to mention here is the problem of locking streams. At least the streams +under control of the system (like +.IR stdin , +.IR stdout , +.IR stderr ) +must be protected by locking the stream with +\fIflockfile\fR(). +But the application itself could have done that, possibly in the same +thread calling +\fIfork\fR(). +In this case, the process will deadlock. +.P +Alternatively, some libraries might have been able to supply just a +.IR child +routine that reinitializes the mutexes in the library and all associated +states to some known value (for example, what it was when the image +was originally executed). This approach is not possible, though, +because implementations are allowed to fail +.IR *_init (\|) +and +.IR *_destroy (\|) +calls for mutexes and locks if the mutex or lock is still locked. In +this case, the +.IR child +routine is not able to reinitialize the mutexes and locks. +.P +When +\fIfork\fR() +is called, only the calling thread is duplicated in the child process. +Synchronization variables remain in the same state in the child as they +were in the parent at the time +\fIfork\fR() +was called. Thus, for example, mutex locks may be held by threads that +no longer exist in the child process, and any associated states may +be inconsistent. The intention was that the parent process could have +avoided this by explicit code that acquires and releases locks critical +to the child via +\fIpthread_atfork\fR(). +In addition, any critical threads would have needed to be recreated and +reinitialized to the proper state in the child (also via +\fIpthread_atfork\fR()). +.P +A higher-level package may acquire locks on its own data structures +before invoking lower-level packages. Under this scenario, the order +specified for fork handler calls allows a simple rule of initialization +for avoiding package deadlock: a package initializes all packages on +which it depends before it calls the +\fIpthread_atfork\fR() +function for itself. +.P +As explained, there is no suitable solution for functionality which +requires non-atomic operations to be protected through mutexes and +locks. This is why the POSIX.1 standard since the 1996 release requires +that the child process after +\fIfork\fR() +in a multi-threaded process only calls async-signal-safe interfaces. +.SH "FUTURE DIRECTIONS" +The +\fIpthread_atfork\fR() +function may be formally deprecated (for example, by shading it OB) in +a future version of this standard. +.SH "SEE ALSO" +.IR "\fIatexit\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_destroy.3p b/upstream/archlinux/man3p/pthread_attr_destroy.3p new file mode 100644 index 00000000..942af40b --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_destroy.3p @@ -0,0 +1,239 @@ +'\" et +.TH PTHREAD_ATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_destroy, +pthread_attr_init +\(em destroy and initialize the thread attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_destroy(pthread_attr_t *\fIattr\fP); +int pthread_attr_init(pthread_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_destroy\fR() +function shall destroy a thread attributes object. An implementation +may cause +\fIpthread_attr_destroy\fR() +to set +.IR attr +to an implementation-defined invalid value. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_attr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIpthread_attr_init\fR() +function shall initialize a thread attributes object +.IR attr +with the default value for all of the individual attributes used by a +given implementation. +.P +The resulting attributes object (possibly modified by setting +individual attribute values) when used by +\fIpthread_create\fR() +defines the attributes of the thread created. A single attributes +object can be used in multiple simultaneous calls to +\fIpthread_create\fR(). +Results are undefined if +\fIpthread_attr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_destroy\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_attr_destroy\fR() +and +\fIpthread_attr_init\fR() +shall return a value of 0; otherwise, an error number shall be returned +to indicate the error. +.SH ERRORS +The +\fIpthread_attr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the thread attributes object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Attributes objects are provided for threads, mutexes, and condition +variables as a mechanism to support probable future standardization in +these areas without requiring that the function itself be changed. +.P +Attributes objects provide clean isolation of the configurable aspects +of threads. For example, ``stack size'' +is an important attribute of a thread, but it cannot be expressed +portably. When porting a threaded program, stack sizes often need to +be adjusted. The use of attributes objects can help by allowing the +changes to be isolated in a single place, rather than being spread +across every instance of thread creation. +.P +Attributes objects can be used to set up ``classes' of threads with +similar attributes; for example, ``threads with large stacks and high +priority'' or ``threads with minimal stacks''. These classes can be +defined in a single place and then referenced wherever threads need to +be created. Changes to ``class'' decisions become straightforward, and +detailed analysis of each +\fIpthread_create\fR() +call is not required. +.P +The attributes objects are defined as opaque types as an aid to +extensibility. If these objects had been specified as structures, +adding new attributes would force recompilation of all multi-threaded +programs when the attributes objects are extended; this might not be +possible if different program components were supplied by different +vendors. +.P +Additionally, opaque attributes objects present opportunities for +improving performance. Argument validity can be checked once when +attributes are set, rather than each time a thread is created. +Implementations often need to cache kernel objects that are expensive +to create. Opaque attributes objects provide an efficient mechanism to +detect when cached objects become invalid due to attribute changes. +.P +Since assignment is not necessarily defined on a given opaque type, +implementation-defined default values cannot be defined in a portable +way. The solution to this problem is to allow attributes objects to be +initialized dynamically by attributes object initialization functions, +so that default values can be supplied automatically by the +implementation. +.P +The following proposal was provided as a suggested alternative to the +supplied attributes: +.IP " 1." 4 +Maintain the style of passing a parameter formed by the +bitwise-inclusive OR of flags to the initialization routines (\c +\fIpthread_create\fR(), +\fIpthread_mutex_init\fR(), +\fIpthread_cond_init\fR()). +The parameter containing the flags should be an opaque type for +extensibility. If no flags are set in the parameter, then the objects +are created with default characteristics. An implementation may +specify implementation-defined flag values and associated behavior. +.IP " 2." 4 +If further specialization of mutexes and condition variables is +necessary, implementations may specify additional procedures that +operate on the +.BR pthread_mutex_t +and +.BR pthread_cond_t +objects (instead of on attributes objects). +.P +The difficulties with this solution are: +.IP " 1." 4 +A bitmask is not opaque if bits have to be set into bitvector +attributes objects using explicitly-coded bitwise-inclusive OR +operations. If the set of options exceeds an +.BR int , +application programmers need to know the location of each bit. If bits +are set or read by encapsulation (that is, get and set functions), then +the bitmask is merely an implementation of attributes objects as +currently defined and should not be exposed to the programmer. +.IP " 2." 4 +Many attributes are not Boolean or very small integral values. For +example, scheduling policy may be placed in 3-bit or 4-bit, but +priority requires 5-bit or more, thereby taking up at least 8 bits out +of a possible 16 bits on machines with 16-bit integers. Because of +this, the bitmask can only reasonably control whether particular +attributes are set or not, and it cannot serve as the repository of the +value itself. The value needs to be specified as a function parameter +(which is non-extensible), or by setting a structure field (which is +non-opaque), or by get and set functions (making the bitmask a +redundant addition to the attributes objects). +.P +Stack size is defined as an optional attribute because the very notion +of a stack is inherently machine-dependent. Some implementations may +not be able to change the size of the stack, for example, and others +may not need to because stack pages may be discontiguous and can be +allocated and released on demand. +.P +The attribute mechanism has been designed in large measure for +extensibility. Future extensions to the attribute mechanism or to any +attributes object defined in this volume of POSIX.1\(hy2017 has to be done with care so +as not to affect binary-compatibility. +.P +Attributes objects, even if allocated by means of dynamic allocation +functions such as +\fImalloc\fR(), +may have their size fixed at compile time. This means, for example, a +\fIpthread_create\fR() +in an implementation with extensions to +.BR pthread_attr_t +cannot look beyond the area that the binary application assumes is +valid. This suggests that implementations should maintain a size field +in the attributes object, as well as possibly version information, if +extensions in different directions (possibly by different vendors) are +to be accommodated. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_destroy\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_init\fR() +refers to an already initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getdetachstate.3p b/upstream/archlinux/man3p/pthread_attr_getdetachstate.3p new file mode 100644 index 00000000..460f4161 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getdetachstate.3p @@ -0,0 +1,175 @@ +'\" et +.TH PTHREAD_ATTR_GETDETACHSTATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +.ad l +pthread_attr_getdetachstate, +pthread_attr_setdetachstate +\(em get and set the detachstate attribute +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getdetachstate(const pthread_attr_t *\fIattr\fP, + int *\fIdetachstate\fP); +int pthread_attr_setdetachstate(pthread_attr_t *\fIattr\fP, int \fIdetachstate\fP); +.fi +.SH DESCRIPTION +The +.IR detachstate +attribute controls whether the thread is created in a detached state. +If the thread is created detached, then use of the ID of the newly +created thread by the +\fIpthread_detach\fR() +or +\fIpthread_join\fR() +function is an error. +.P +The +\fIpthread_attr_getdetachstate\fR() +and +\fIpthread_attr_setdetachstate\fR() +functions, respectively, shall get and set the +.IR detachstate +attribute in the +.IR attr +object. +.P +For +\fIpthread_attr_getdetachstate\fR(), +.IR detachstate +shall be set to either PTHREAD_CREATE_DETACHED or +PTHREAD_CREATE_JOINABLE. +.P +For +\fIpthread_attr_setdetachstate\fR(), +the application shall set +.IR detachstate +to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE. +.P +A value of PTHREAD_CREATE_DETACHED shall cause all threads created with +.IR attr +to be in the detached state, whereas using a value of +PTHREAD_CREATE_JOINABLE shall cause all threads created with +.IR attr +to be in the joinable state. The default value of the +.IR detachstate +attribute shall be PTHREAD_CREATE_JOINABLE. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getdetachstate\fR() +or +\fIpthread_attr_setdetachstate\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_attr_getdetachstate\fR() +and +\fIpthread_attr_setdetachstate\fR() +shall return a value of 0; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_attr_getdetachstate\fR() +function stores the value of the +.IR detachstate +attribute in +.IR detachstate +if successful. +.SH ERRORS +The +\fIpthread_attr_setdetachstate\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR detachstate +was not valid +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Retrieving the detachstate Attribute" +.P +This example shows how to obtain the +.IR detachstate +attribute of a thread attribute object. +.sp +.RS 4 +.nf + +#include +.P +pthread_attr_t thread_attr; +int detachstate; +int rc; +.P +/* code initializing thread_attr */ +\&... +.P +rc = pthread_attr_getdetachstate (&thread_attr, &detachstate); +if (rc!=0) { + /* handle error */ + ... +} +else { + /* legal values for detachstate are: + * PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE + */ + ... +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getdetachstate\fR() +or +\fIpthread_attr_setdetachstate\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getguardsize.3p b/upstream/archlinux/man3p/pthread_attr_getguardsize.3p new file mode 100644 index 00000000..ba2fb1bd --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getguardsize.3p @@ -0,0 +1,217 @@ +'\" et +.TH PTHREAD_ATTR_GETGUARDSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +.ad l +pthread_attr_getguardsize, +pthread_attr_setguardsize +\(em get and set the thread guardsize attribute +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getguardsize(const pthread_attr_t *restrict \fIattr\fP, + size_t *restrict \fIguardsize\fP); +int pthread_attr_setguardsize(pthread_attr_t *\fIattr\fP, + size_t \fIguardsize\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getguardsize\fR() +function shall get the +.IR guardsize +attribute in the +.IR attr +object. This attribute shall be returned in the +.IR guardsize +parameter. +.P +The +\fIpthread_attr_setguardsize\fR() +function shall set the +.IR guardsize +attribute in the +.IR attr +object. The new value of this attribute shall be obtained from the +.IR guardsize +parameter. If +.IR guardsize +is zero, a guard area shall not be provided for threads created with +.IR attr . +If +.IR guardsize +is greater than zero, a guard area of at least size +.IR guardsize +bytes shall be provided for each thread created with +.IR attr . +.P +The +.IR guardsize +attribute controls the size of the guard area for the created thread's +stack. The +.IR guardsize +attribute provides protection against overflow of the stack pointer. If +a thread's stack is created with guard protection, the implementation +allocates extra memory at the overflow end of the stack as a buffer +against stack overflow of the stack pointer. If an application +overflows into this buffer an error shall result (possibly in a SIGSEGV +signal being delivered to the thread). +.P +A conforming implementation may round up the value contained in +.IR guardsize +to a multiple of the configurable system variable +{PAGESIZE} +(see +.IR ). +If an implementation rounds up the value of +.IR guardsize +to a multiple of +{PAGESIZE}, +a call to +\fIpthread_attr_getguardsize\fR() +specifying +.IR attr +shall store in the +.IR guardsize +parameter the guard size specified by the previous +\fIpthread_attr_setguardsize\fR() +function call. +.P +The default value of the +.IR guardsize +attribute is implementation-defined. +.P +If the +.IR stackaddr +attribute has been set (that is, the caller is allocating and managing +its own thread stacks), the +.IR guardsize +attribute shall be ignored and no protection shall be provided by the +implementation. It is the responsibility of the application to manage +stack overflow along with stack allocation and management in this +case. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getguardsize\fR() +or +\fIpthread_attr_setguardsize\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getguardsize\fR() +and +\fIpthread_attr_setguardsize\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The parameter +.IR guardsize +is invalid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Retrieving the guardsize Attribute" +.P +This example shows how to obtain the +.IR guardsize +attribute of a thread attribute object. +.sp +.RS 4 +.nf + +#include +.P +pthread_attr_t thread_attr; +size_t guardsize; +int rc; +.P +/* code initializing thread_attr */ +\&... +.P +rc = pthread_attr_getguardsize (&thread_attr, &guardsize); +if (rc != 0) { + /* handle error */ + ... +} +else { + if (guardsize > 0) { + /* a guard area of at least guardsize bytes is provided */ + ... + } + else { + /* no guard area provided */ + ... + } +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +.IR guardsize +attribute is provided to the application for two reasons: +.IP " 1." 4 +Overflow protection can potentially result in wasted system resources. +An application that creates a large number of threads, and which knows +its threads never overflow their stack, can save system resources by +turning off guard areas. +.IP " 2." 4 +When threads allocate large data structures on the stack, large guard +areas may be needed to detect stack overflow. +.P +The default size of the guard area is left implementation-defined +since on systems supporting very large page sizes, the overhead +might be substantial if at least one guard page is required by default. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getguardsize\fR() +or +\fIpthread_attr_setguardsize\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getinheritsched.3p b/upstream/archlinux/man3p/pthread_attr_getinheritsched.3p new file mode 100644 index 00000000..47a2cd8b --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getinheritsched.3p @@ -0,0 +1,161 @@ +'\" et +.TH PTHREAD_ATTR_GETINHERITSCHED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_getinheritsched, +pthread_attr_setinheritsched +\(em get and set the inheritsched attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getinheritsched(const pthread_attr_t *restrict \fIattr\fP, + int *restrict \fIinheritsched\fP); +int pthread_attr_setinheritsched(pthread_attr_t *\fIattr\fP, + int \fIinheritsched\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getinheritsched\fR() +and +\fIpthread_attr_setinheritsched\fR() +functions, respectively, shall get and set the +.IR inheritsched +attribute in the +.IR attr +argument. +.P +When the attributes objects are used by +\fIpthread_create\fR(), +the +.IR inheritsched +attribute determines how the other scheduling attributes of the created +thread shall be set. +.P +The supported values of +.IR inheritsched +shall be: +.IP PTHREAD_INHERIT_SCHED 6 +.br +Specifies that the thread scheduling attributes shall be inherited from +the creating thread, and the scheduling attributes in this +.IR attr +argument shall be ignored. +.IP PTHREAD_EXPLICIT_SCHED 6 +.br +Specifies that the thread scheduling attributes shall be set to the +corresponding values from this attributes object. +.P +The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are +defined in the +.IR +header. +.P +The following thread scheduling attributes defined by POSIX.1\(hy2008 are +affected by the +.IR inheritsched +attribute: scheduling policy (\c +.IR schedpolicy ), +scheduling parameters (\c +.IR schedparam ), +and scheduling contention scope (\c +.IR contentionscope ). +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getinheritsched\fR() +or +\fIpthread_attr_setinheritsched\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getinheritsched\fR() +and +\fIpthread_attr_setinheritsched\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setinheritsched\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setinheritsched\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR inheritsched +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.P +See +.IR "Section 2.9.4" ", " "Thread Scheduling" +for further details on thread scheduling attributes and their default +settings. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getinheritsched\fR() +or +\fIpthread_attr_setinheritsched\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getschedparam.3p b/upstream/archlinux/man3p/pthread_attr_getschedparam.3p new file mode 100644 index 00000000..29707bb9 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getschedparam.3p @@ -0,0 +1,152 @@ +'\" et +.TH PTHREAD_ATTR_GETSCHEDPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_getschedparam, +pthread_attr_setschedparam +\(em get and set the schedparam attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getschedparam(const pthread_attr_t *restrict \fIattr\fP, + struct sched_param *restrict \fIparam\fP); +int pthread_attr_setschedparam(pthread_attr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getschedparam\fR() +and +\fIpthread_attr_setschedparam\fR() +functions, respectively, shall get and set the scheduling parameter +attributes in the +.IR attr +argument. The contents of the +.IR param +structure are defined in the +.IR +header. For the SCHED_FIFO and SCHED_RR policies, +the only required member of +.IR param +is +.IR sched_priority . +.P +For the SCHED_SPORADIC policy, the required members of the +.IR param +structure are +.IR sched_priority , +.IR sched_ss_low_priority , +.IR sched_ss_repl_period , +.IR sched_ss_init_budget , +and +.IR sched_ss_max_repl . +The specified +.IR sched_ss_repl_period +must be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,\c +{SS_REPL_MAX}] +for the function to succeed; if not, the function shall fail. +It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedparam\fR() +or +\fIpthread_attr_setschedparam\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getschedparam\fR() +and +\fIpthread_attr_setschedparam\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setschedparam\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setschedparam\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR param +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedparam\fR() +or +\fIpthread_attr_setschedparam\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getschedpolicy.3p b/upstream/archlinux/man3p/pthread_attr_getschedpolicy.3p new file mode 100644 index 00000000..f1753f5f --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getschedpolicy.3p @@ -0,0 +1,135 @@ +'\" et +.TH PTHREAD_ATTR_GETSCHEDPOLICY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_getschedpolicy, +pthread_attr_setschedpolicy +\(em get and set the schedpolicy attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getschedpolicy(const pthread_attr_t *restrict \fIattr\fP, + int *restrict \fIpolicy\fP); +int pthread_attr_setschedpolicy(pthread_attr_t *\fIattr\fP, int \fIpolicy\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getschedpolicy\fR() +and +\fIpthread_attr_setschedpolicy\fR() +functions, respectively, shall get and set the +.IR schedpolicy +attribute in the +.IR attr +argument. +.P +The supported values of +.IR policy +shall include SCHED_FIFO, SCHED_RR, and SCHED_OTHER, +which are defined in the +.IR +header. When threads executing with the scheduling policy SCHED_FIFO, +SCHED_RR, +or SCHED_SPORADIC +are waiting on a mutex, they shall acquire the mutex in priority order +when the mutex is unlocked. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedpolicy\fR() +or +\fIpthread_attr_setschedpolicy\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getschedpolicy\fR() +and +\fIpthread_attr_setschedpolicy\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setschedpolicy\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setschedpolicy\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR policy +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.P +See +.IR "Section 2.9.4" ", " "Thread Scheduling" +for further details on thread scheduling attributes and their +default settings. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getschedpolicy\fR() +or +\fIpthread_attr_setschedpolicy\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getscope\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getscope.3p b/upstream/archlinux/man3p/pthread_attr_getscope.3p new file mode 100644 index 00000000..5b8d4648 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getscope.3p @@ -0,0 +1,134 @@ +'\" et +.TH PTHREAD_ATTR_GETSCOPE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_getscope, +pthread_attr_setscope +\(em get and set the contentionscope attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getscope(const pthread_attr_t *restrict \fIattr\fP, + int *restrict \fIcontentionscope\fP); +int pthread_attr_setscope(pthread_attr_t *\fIattr\fP, int \fIcontentionscope\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getscope\fR() +and +\fIpthread_attr_setscope\fR() +functions, respectively, shall get and set the +.IR contentionscope +attribute in the +.IR attr +object. +.P +The +.IR contentionscope +attribute may have the values PTHREAD_SCOPE_SYSTEM, +signifying system scheduling contention scope, or +PTHREAD_SCOPE_PROCESS, +signifying process scheduling contention scope. The symbols +PTHREAD_SCOPE_SYSTEM and PTHREAD_SCOPE_PROCESS are defined in the +.IR +header. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getscope\fR() +or +\fIpthread_attr_setscope\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_attr_getscope\fR() +and +\fIpthread_attr_setscope\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_attr_setscope\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the attribute to an unsupported value. +.P +The +\fIpthread_attr_setscope\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR contentionscope +is not valid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +After these attributes have been set, a thread can be created with the +specified attributes using +\fIpthread_create\fR(). +Using these routines does not affect the current running thread. +.P +See +.IR "Section 2.9.4" ", " "Thread Scheduling" +for further details on thread scheduling attributes and their default +settings. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getscope\fR() +or +\fIpthread_attr_setscope\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)", +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)", +.IR "\fIpthread_attr_getschedparam\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getstack.3p b/upstream/archlinux/man3p/pthread_attr_getstack.3p new file mode 100644 index 00000000..6a666650 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getstack.3p @@ -0,0 +1,203 @@ +'\" et +.TH PTHREAD_ATTR_GETSTACK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_getstack, +pthread_attr_setstack +\(em get and set stack attributes +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getstack(const pthread_attr_t *restrict \fIattr\fP, + void **restrict \fIstackaddr\fP, size_t *restrict \fIstacksize\fP); +int pthread_attr_setstack(pthread_attr_t *\fIattr\fP, void *\fIstackaddr\fP, + size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getstack\fR() +and +\fIpthread_attr_setstack\fR() +functions, respectively, shall get and set the thread creation stack +attributes +.IR stackaddr +and +.IR stacksize +in the +.IR attr +object. +.P +The stack attributes specify the area of storage to be used for the +created thread's stack. The base (lowest addressable byte) of the +storage shall be +.IR stackaddr , +and the size of the storage shall be +.IR stacksize +bytes. The +.IR stacksize +shall be at least +{PTHREAD_STACK_MIN}. +The +\fIpthread_attr_setstack\fR() +function may fail with +.BR [EINVAL] +if +.IR stackaddr +does not meet implementation-defined alignment requirements. +All pages within the stack described by +.IR stackaddr +and +.IR stacksize +shall be both readable and writable by the thread. +.P +If the +\fIpthread_attr_getstack\fR() +function is called before the +.IR stackaddr +attribute has been set, the behavior is unspecified. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getstack\fR() +or +\fIpthread_attr_setstack\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +.P +The +\fIpthread_attr_getstack\fR() +function shall store the stack attribute values in +.IR stackaddr +and +.IR stacksize +if successful. +.SH ERRORS +.P +The +\fIpthread_attr_setstack\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR stacksize +is less than +{PTHREAD_STACK_MIN} +or exceeds an implementation-defined limit. +.P +The +\fIpthread_attr_setstack\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR stackaddr +does not have proper alignment to be used as a stack, or ((\c +.BR "char *" )\c +.IR stackaddr ++ +.IR stacksize ) +lacks proper alignment. +.TP +.BR EACCES +The stack page(s) described by +.IR stackaddr +and +.IR stacksize +are not both readable and writable by the thread. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are appropriate for use by applications in an +environment where the stack for a thread must be placed in some +particular region of memory. +.P +While it might seem that an application could detect stack overflow by +providing a protected page outside the specified stack region, this +cannot be done portably. Implementations are free to place the thread's +initial stack pointer anywhere within the specified region to +accommodate the machine's stack pointer behavior and allocation +requirements. Furthermore, on some architectures, such as the IA\(hy64, +``overflow'' might mean that two separate stack pointers allocated +within the region will overlap somewhere in the middle of the region. +.P +After a successful call to +\fIpthread_attr_setstack\fR(), +the storage area specified by the +.IR stackaddr +parameter is under the control of the implementation, as described in +.IR "Section 2.9.8" ", " "Use of Application-Managed Thread Stacks". +.P +The specification of the +.IR stackaddr +attribute presents several ambiguities that make portable use of these +functions impossible. For example, the standard allows implementations +to impose arbitrary alignment requirements on +.IR stackaddr . +Applications cannot assume that a buffer obtained from +\fImalloc\fR() +is suitably aligned. Note that although the +.IR stacksize +value passed to +\fIpthread_attr_setstack\fR() +must satisfy alignment requirements, the same is not true for +\fIpthread_attr_setstacksize\fR() +where the implementation must increase the specified size if +necessary to achieve the proper alignment. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getstack\fR() +or +\fIpthread_attr_setstack\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_attr_getstacksize\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_getstacksize.3p b/upstream/archlinux/man3p/pthread_attr_getstacksize.3p new file mode 100644 index 00000000..45c5f206 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_getstacksize.3p @@ -0,0 +1,121 @@ +'\" et +.TH PTHREAD_ATTR_GETSTACKSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +.ad l +pthread_attr_getstacksize, +pthread_attr_setstacksize +\(em get and set the stacksize attribute +.ad b +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_getstacksize(const pthread_attr_t *restrict \fIattr\fP, + size_t *restrict \fIstacksize\fP); +int pthread_attr_setstacksize(pthread_attr_t *\fIattr\fP, size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_attr_getstacksize\fR() +and +\fIpthread_attr_setstacksize\fR() +functions, respectively, shall get and set the thread creation +.IR stacksize +attribute in the +.IR attr +object. +.P +The +.IR stacksize +attribute shall define the minimum stack size (in bytes) allocated +for the created threads stack. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_attr_getstacksize\fR() +or +\fIpthread_attr_setstacksize\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_attr_getstacksize\fR() +and +\fIpthread_attr_setstacksize\fR() +shall return a value of 0; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_attr_getstacksize\fR() +function stores the +.IR stacksize +attribute value in +.IR stacksize +if successful. +.SH ERRORS +The +\fIpthread_attr_setstacksize\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR stacksize +is less than +{PTHREAD_STACK_MIN} +or exceeds a system-imposed limit. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_attr_getstacksize\fR() +or +\fIpthread_attr_setstacksize\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_init.3p b/upstream/archlinux/man3p/pthread_attr_init.3p new file mode 100644 index 00000000..19972c6a --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_init.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_ATTR_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_init +\(em initialize the thread attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_init(pthread_attr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setdetachstate.3p b/upstream/archlinux/man3p/pthread_attr_setdetachstate.3p new file mode 100644 index 00000000..fc7b74b5 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setdetachstate.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_ATTR_SETDETACHSTATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setdetachstate +\(em set the detachstate attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setdetachstate(pthread_attr_t *\fIattr\fP, int \fIdetachstate\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getdetachstate\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setguardsize.3p b/upstream/archlinux/man3p/pthread_attr_setguardsize.3p new file mode 100644 index 00000000..9ec21082 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setguardsize.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_ATTR_SETGUARDSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setguardsize +\(em set the thread guardsize attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setguardsize(pthread_attr_t *\fIattr\fP, + size_t \fIguardsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getguardsize\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setinheritsched.3p b/upstream/archlinux/man3p/pthread_attr_setinheritsched.3p new file mode 100644 index 00000000..23f22494 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setinheritsched.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_ATTR_SETINHERITSCHED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setinheritsched +\(em set the inheritsched attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setinheritsched(pthread_attr_t *\fIattr\fP, + int \fIinheritsched\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getinheritsched\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setschedparam.3p b/upstream/archlinux/man3p/pthread_attr_setschedparam.3p new file mode 100644 index 00000000..9620e610 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setschedparam.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_ATTR_SETSCHEDPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setschedparam +\(em set the schedparam attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setschedparam(pthread_attr_t *restrict \fIattr\fP, + const struct sched_param *restrict \fIparam\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getschedparam\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setschedpolicy.3p b/upstream/archlinux/man3p/pthread_attr_setschedpolicy.3p new file mode 100644 index 00000000..6591326d --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setschedpolicy.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_ATTR_SETSCHEDPOLICY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setschedpolicy +\(em set the schedpolicy attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setschedpolicy(pthread_attr_t *\fIattr\fP, int \fIpolicy\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getschedpolicy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setscope.3p b/upstream/archlinux/man3p/pthread_attr_setscope.3p new file mode 100644 index 00000000..7639b326 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setscope.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_ATTR_SETSCOPE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setscope +\(em set the contentionscope attribute +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setscope(pthread_attr_t *\fIattr\fP, int \fIcontentionscope\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getscope\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setstack.3p b/upstream/archlinux/man3p/pthread_attr_setstack.3p new file mode 100644 index 00000000..a15470b2 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setstack.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_ATTR_SETSTACK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setstack +\(em set the stack attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setstack(pthread_attr_t *\fIattr\fP, void *\fIstackaddr\fP, + size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getstack\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_attr_setstacksize.3p b/upstream/archlinux/man3p/pthread_attr_setstacksize.3p new file mode 100644 index 00000000..c7199d6e --- /dev/null +++ b/upstream/archlinux/man3p/pthread_attr_setstacksize.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_ATTR_SETSTACKSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_attr_setstacksize +\(em set the stacksize attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_attr_setstacksize(pthread_attr_t *\fIattr\fP, size_t \fIstacksize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_attr_getstacksize\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_barrier_destroy.3p b/upstream/archlinux/man3p/pthread_barrier_destroy.3p new file mode 100644 index 00000000..aadc53e6 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_barrier_destroy.3p @@ -0,0 +1,165 @@ +'\" et +.TH PTHREAD_BARRIER_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_barrier_destroy, +pthread_barrier_init +\(em destroy and initialize a barrier object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrier_destroy(pthread_barrier_t *\fIbarrier\fP); +int pthread_barrier_init(pthread_barrier_t *restrict \fIbarrier\fP, + const pthread_barrierattr_t *restrict \fIattr\fP, unsigned \fIcount\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrier_destroy\fR() +function shall destroy the barrier referenced by +.IR barrier +and release any resources used by the barrier. The effect of +subsequent use of the barrier is undefined until the barrier is +reinitialized by another call to +\fIpthread_barrier_init\fR(). +An implementation may use this function to set +.IR barrier +to an invalid value. The results are undefined if +\fIpthread_barrier_destroy\fR() +is called when any thread is blocked on the barrier, or if this +function is called with an uninitialized barrier. +.P +The +\fIpthread_barrier_init\fR() +function shall allocate any resources required to use the barrier +referenced by +.IR barrier +and shall initialize the barrier with attributes referenced by +.IR attr . +If +.IR attr +is NULL, the default barrier attributes shall be used; the effect is +the same as passing the address of a default barrier attributes +object. The results are undefined if +\fIpthread_barrier_init\fR() +is called when any thread is blocked on the barrier (that is, has not +returned from the +\fIpthread_barrier_wait\fR() +call). The results are undefined if a barrier is used without first +being initialized. The results are undefined if +\fIpthread_barrier_init\fR() +is called specifying an already initialized barrier. +.P +The +.IR count +argument specifies the number of threads that must call +\fIpthread_barrier_wait\fR() +before any of them successfully return from the call. The value +specified by +.IR count +must be greater than zero. +.P +If the +\fIpthread_barrier_init\fR() +function fails, the barrier shall not be initialized and the contents +of +.IR barrier +are undefined. +.P +See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIpthread_barrier_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacks the necessary resources to initialize another barrier. +.TP +.BR EINVAL +The value specified by +.IR count +is equal to zero. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the barrier. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_destroy\fR() +does not refer to an initialized barrier object, it is recommended that +the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_barrier_init\fR() +does not refer to an initialized barrier attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_destroy\fR() +or +\fIpthread_barrier_init\fR() +refers to a barrier that is in use (for example, in a +\fIpthread_barrier_wait\fR() +call) by another thread, or detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_init\fR() +refers to an already initialized barrier object, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_barrier_wait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_barrier_wait.3p b/upstream/archlinux/man3p/pthread_barrier_wait.3p new file mode 100644 index 00000000..f267d3ff --- /dev/null +++ b/upstream/archlinux/man3p/pthread_barrier_wait.3p @@ -0,0 +1,114 @@ +'\" et +.TH PTHREAD_BARRIER_WAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_barrier_wait +\(em synchronize at a barrier +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrier_wait(pthread_barrier_t *\fIbarrier\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrier_wait\fR() +function shall synchronize participating threads at the barrier +referenced by +.IR barrier . +The calling thread shall block until the required number of +threads have called +\fIpthread_barrier_wait\fR() +specifying the barrier. +.P +When the required number of threads have called +\fIpthread_barrier_wait\fR() +specifying the barrier, the constant PTHREAD_BARRIER_SERIAL_THREAD +shall be returned to one unspecified thread and zero shall be returned +to each of the remaining threads. At this point, the barrier shall be +reset to the state it had as a result of the most recent +\fIpthread_barrier_init\fR() +function that referenced it. +.P +The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in +.IR +and its value shall be distinct from any other value returned by +\fIpthread_barrier_wait\fR(). +.P +The results are undefined if this function is called with an +uninitialized barrier. +.P +If a signal is delivered to a thread blocked on a barrier, upon return +from the signal handler the thread shall resume waiting at the barrier +if the barrier wait has not completed (that is, if the required number +of threads have not arrived at the barrier during the execution of the +signal handler); otherwise, the thread shall continue as normal from +the completed barrier wait. Until the thread in the signal handler +returns from it, it is unspecified whether other threads may proceed +past the barrier once they have all reached it. +.P +A thread that has blocked on a barrier shall not prevent any unblocked +thread that is eligible to use the same processing resources from +eventually making forward progress in its execution. Eligibility for +processing resources shall be determined by the scheduling policy. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_barrier_wait\fR() +function shall return PTHREAD_BARRIER_SERIAL_THREAD for a single +(arbitrary) thread synchronized at the barrier and zero for each of the +other threads. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR barrier +argument to +\fIpthread_barrier_wait\fR() +does not refer to an initialized barrier object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_barrier_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_barrierattr_destroy.3p b/upstream/archlinux/man3p/pthread_barrierattr_destroy.3p new file mode 100644 index 00000000..4cd627f6 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_barrierattr_destroy.3p @@ -0,0 +1,115 @@ +'\" et +.TH PTHREAD_BARRIERATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_barrierattr_destroy, +pthread_barrierattr_init +\(em destroy and initialize the barrier attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_destroy(pthread_barrierattr_t *\fIattr\fP); +int pthread_barrierattr_init(pthread_barrierattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrierattr_destroy\fR() +function shall destroy a barrier attributes object. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_barrierattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. An implementation may cause +\fIpthread_barrierattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +The +\fIpthread_barrierattr_init\fR() +function shall initialize a barrier attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +If +\fIpthread_barrierattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object, the results are undefined. +.P +After a barrier attributes object has been used to initialize one or +more barriers, any function affecting the attributes object (including +destruction) shall not affect any previously initialized barrier. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_destroy\fR() +does not refer to an initialized barrier attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_barrierattr_destroy\fR() +and +\fIpthread_barrierattr_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_barrierattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the barrier attributes +object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_destroy\fR() +does not refer to an initialized barrier attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_barrierattr_getpshared\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_barrierattr_getpshared.3p b/upstream/archlinux/man3p/pthread_barrierattr_getpshared.3p new file mode 100644 index 00000000..d8c641a8 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_barrierattr_getpshared.3p @@ -0,0 +1,139 @@ +'\" et +.TH PTHREAD_BARRIERATTR_GETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_barrierattr_getpshared, +pthread_barrierattr_setpshared +\(em get and set the process-shared attribute of the barrier +attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_getpshared(const pthread_barrierattr_t + *restrict \fIattr\fP, int *restrict \fIpshared\fP); +int pthread_barrierattr_setpshared(pthread_barrierattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_barrierattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the attributes object referenced by +.IR attr . +The +\fIpthread_barrierattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute is set to PTHREAD_PROCESS_SHARED to +permit a barrier to be operated upon by any thread that has access to +the memory where the barrier is allocated. See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. The default value of the attribute +shall be PTHREAD_PROCESS_PRIVATE. Both constants +PTHREAD_PROCESS_SHARED and PTHREAD_PROCESS_PRIVATE are defined in +.IR . +.P +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_getpshared\fR() +or +\fIpthread_barrierattr_setpshared\fR() +does not refer to an initialized barrier attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_barrierattr_getpshared\fR() +function shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +.P +If successful, the +\fIpthread_barrierattr_setpshared\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_barrierattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the +.IR process-shared +attribute is not one of the legal values PTHREAD_PROCESS_SHARED +or PTHREAD_PROCESS_PRIVATE. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_barrierattr_getpshared\fR() +and +\fIpthread_barrierattr_setpshared\fR() +functions are part of the Thread Process-Shared Synchronization +option and need not be provided on all implementations. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_barrierattr_getpshared\fR() +or +\fIpthread_barrierattr_setpshared\fR() +does not refer to an initialized barrier attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_barrier_destroy\fR\^(\|)", +.IR "\fIpthread_barrierattr_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_barrierattr_init.3p b/upstream/archlinux/man3p/pthread_barrierattr_init.3p new file mode 100644 index 00000000..dd477dd8 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_barrierattr_init.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_BARRIERATTR_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_barrierattr_init +\(em initialize the barrier attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_init(pthread_barrierattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_barrierattr_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_barrierattr_setpshared.3p b/upstream/archlinux/man3p/pthread_barrierattr_setpshared.3p new file mode 100644 index 00000000..809c506c --- /dev/null +++ b/upstream/archlinux/man3p/pthread_barrierattr_setpshared.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_BARRIERATTR_SETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_barrierattr_setpshared +\(em set the process-shared attribute of the barrier attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_barrierattr_setpshared(pthread_barrierattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_barrierattr_getpshared\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_cancel.3p b/upstream/archlinux/man3p/pthread_cancel.3p new file mode 100644 index 00000000..334b6451 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_cancel.3p @@ -0,0 +1,123 @@ +'\" et +.TH PTHREAD_CANCEL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_cancel +\(em cancel execution of a thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cancel(pthread_t \fIthread\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_cancel\fR() +function shall request that +.IR thread +be canceled. The target thread's cancelability state and type +determines when the cancellation takes effect. When the cancellation +is acted on, the cancellation cleanup handlers for +.IR thread +shall be called. When the last cancellation cleanup handler returns, +the thread-specific data destructor functions shall be called for +.IR thread . +When the last destructor function returns, +.IR thread +shall be terminated. +.P +The cancellation processing in the target thread shall run +asynchronously with respect to the calling thread returning from +\fIpthread_cancel\fR(). +.SH "RETURN VALUE" +If successful, the +\fIpthread_cancel\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_cancel\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Two alternative functions were considered for sending the cancellation +notification to a thread. One would be to define a new SIGCANCEL +signal that had the cancellation semantics when delivered; the other was +to define the new +\fIpthread_cancel\fR() +function, which would trigger the cancellation semantics. +.P +The advantage of a new signal was that so much of the delivery criteria +were identical to that used when trying to deliver a signal that making +cancellation notification a signal was seen as consistent. Indeed, many +implementations implement cancellation using a special signal. On the +other hand, there would be no signal functions that could be used with +this signal except +\fIpthread_kill\fR(), +and the behavior of the delivered cancellation signal would be unlike +any previously existing defined signal. +.P +The benefits of a special function include the recognition that this +signal would be defined because of the similar delivery criteria and +that this is the only common behavior between a cancellation request and +a signal. In addition, the cancellation delivery mechanism does not +have to be implemented as a signal. There are also strong, if not +stronger, parallels with language exception mechanisms than with +signals that are potentially obscured if the delivery mechanism is +visibly closer to signals. +.P +In the end, it was considered that as there were so many exceptions to +the use of the new signal with existing signals functions it +would be misleading. A special function has resolved this problem. +This function was carefully defined so that an implementation wishing +to provide the cancellation functions on top of signals could do so. +The special function also means that implementations are not obliged +to implement cancellation with signals. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_exit\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)", +.IR "\fIpthread_setcancelstate\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_cleanup_pop.3p b/upstream/archlinux/man3p/pthread_cleanup_pop.3p new file mode 100644 index 00000000..ab519f5f --- /dev/null +++ b/upstream/archlinux/man3p/pthread_cleanup_pop.3p @@ -0,0 +1,343 @@ +'\" et +.TH PTHREAD_CLEANUP_POP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_cleanup_pop, +pthread_cleanup_push +\(em establish cancellation handlers +.SH SYNOPSIS +.LP +.nf +#include +.P +void pthread_cleanup_pop(int \fIexecute\fP); +void pthread_cleanup_push(void (*\fIroutine\fP)(void*), void *\fIarg\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_cleanup_pop\fR() +function shall remove the routine at the top of the calling thread's +cancellation cleanup stack and optionally invoke it (if +.IR execute +is non-zero). +.P +The +\fIpthread_cleanup_push\fR() +function shall push the specified cancellation cleanup handler +.IR routine +onto the calling thread's cancellation cleanup stack. The cancellation +cleanup handler shall be popped from the cancellation cleanup stack and +invoked with the argument +.IR arg +when: +.IP " *" 4 +The thread exits (that is, calls +\fIpthread_exit\fR()). +.IP " *" 4 +The thread acts upon a cancellation request. +.IP " *" 4 +The thread calls +\fIpthread_cleanup_pop\fR() +with a non-zero +.IR execute +argument. +.P +It is unspecified whether +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR() +are macros or functions. If a macro definition is suppressed in order +to access an actual function, or a program defines an external +identifier with any of these names, the behavior is undefined. +The application shall ensure that they appear as statements, +and in pairs within the same lexical scope (that is, the +\fIpthread_cleanup_push\fR() +macro may be thought to expand to a token list whose first token is +.BR '{' +with +\fIpthread_cleanup_pop\fR() +expanding to a token list whose last token is the corresponding +.BR '}' ). +.P +The effect of calling +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +is undefined if there have been any calls to +\fIpthread_cleanup_push\fR() +or +\fIpthread_cleanup_pop\fR() +made without the matching call since the jump buffer was filled. The +effect of calling +\fIlongjmp\fR() +or +\fIsiglongjmp\fR() +from inside a cancellation cleanup handler is also undefined unless the +jump buffer was also filled in the cancellation cleanup handler. +.P +The effect of the use of +.BR return , +.BR break , +.BR continue , +and +.BR goto +to prematurely leave a code block described by a pair of +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR() +functions calls is undefined. +.SH "RETURN VALUE" +The +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR() +functions shall not return a value. +.SH ERRORS +No errors are defined. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following is an example using thread primitives to implement a +cancelable, writers-priority read-write lock: +.sp +.RS 4 +.nf + +typedef struct { + pthread_mutex_t lock; + pthread_cond_t rcond, + wcond; + int lock_count; /* < 0 .. Held by writer. */ + /* > 0 .. Held by lock_count readers. */ + /* = 0 .. Held by nobody. */ + int waiting_writers; /* Count of waiting writers. */ +} rwlock; +.P +void +waiting_reader_cleanup(void *arg) +{ + rwlock *l; +.P + l = (rwlock *) arg; + pthread_mutex_unlock(&l->lock); +} +.P +void +lock_for_read(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + pthread_cleanup_push(waiting_reader_cleanup, l); + while ((l->lock_count < 0) || (l->waiting_writers != 0)) + pthread_cond_wait(&l->rcond, &l->lock); + l->lock_count++; + /* + * Note the pthread_cleanup_pop executes + * waiting_reader_cleanup. + */ + pthread_cleanup_pop(1); +} +.P +void +release_read_lock(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + if (--l->lock_count == 0) + pthread_cond_signal(&l->wcond); + pthread_mutex_unlock(&l->lock); +} +.P +void +waiting_writer_cleanup(void *arg) +{ + rwlock *l; +.P + l = (rwlock *) arg; + if ((--l->waiting_writers == 0) && (l->lock_count >= 0)) { + /* + * This only happens if we have been canceled. If the + * lock is not held by a writer, there may be readers who + * were blocked because waiting_writers was positive; they + * can now be unblocked. + */ + pthread_cond_broadcast(&l->rcond); + } + pthread_mutex_unlock(&l->lock); +} +.P +void +lock_for_write(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + l->waiting_writers++; + pthread_cleanup_push(waiting_writer_cleanup, l); + while (l->lock_count != 0) + pthread_cond_wait(&l->wcond, &l->lock); + l->lock_count = -1; + /* + * Note the pthread_cleanup_pop executes + * waiting_writer_cleanup. + */ + pthread_cleanup_pop(1); +} +.P +void +release_write_lock(rwlock *l) +{ + pthread_mutex_lock(&l->lock); + l->lock_count = 0; + if (l->waiting_writers == 0) + pthread_cond_broadcast(&l->rcond); + else + pthread_cond_signal(&l->wcond); + pthread_mutex_unlock(&l->lock); +} +.P +/* + * This function is called to initialize the read/write lock. + */ +void +initialize_rwlock(rwlock *l) +{ + pthread_mutex_init(&l->lock, pthread_mutexattr_default); + pthread_cond_init(&l->wcond, pthread_condattr_default); + pthread_cond_init(&l->rcond, pthread_condattr_default); + l->lock_count = 0; + l->waiting_writers = 0; +} +.P +reader_thread() +{ + lock_for_read(&lock); + pthread_cleanup_push(release_read_lock, &lock); + /* + * Thread has read lock. + */ + pthread_cleanup_pop(1); +} +.P +writer_thread() +{ + lock_for_write(&lock); + pthread_cleanup_push(release_write_lock, &lock); + /* + * Thread has write lock. + */ +pthread_cleanup_pop(1); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The two routines that push and pop cancellation cleanup handlers, +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR(), +can be thought of as left and right-parentheses. They always need to +be matched. +.SH RATIONALE +The restriction that the two routines that push and pop +cancellation cleanup handlers, +\fIpthread_cleanup_push\fR() +and +\fIpthread_cleanup_pop\fR(), +have to appear in the same lexical scope allows for efficient macro or +compiler implementations and efficient storage management. A sample +implementation of these routines as macros might look like this: +.sp +.RS 4 +.nf + +#define pthread_cleanup_push(rtn,arg) { \e + struct _pthread_handler_rec __cleanup_handler, **__head; \e + __cleanup_handler.rtn = rtn; \e + __cleanup_handler.arg = arg; \e + (void) pthread_getspecific(_pthread_handler_key, &__head); \e + __cleanup_handler.next = *__head; \e + *__head = &__cleanup_handler; +.P +#define pthread_cleanup_pop(ex) \e + *__head = __cleanup_handler.next; \e + if (ex) (*__cleanup_handler.rtn)(__cleanup_handler.arg); \e +} +.fi +.P +.RE +.P +A more ambitious implementation of these routines might do even better +by allowing the compiler to note that the +cancellation cleanup handler is a constant and can be expanded inline. +.P +This volume of POSIX.1\(hy2017 currently leaves unspecified the effect of calling +\fIlongjmp\fR() +from a signal handler executing in a POSIX System Interfaces function. +If an implementation wants to allow this and give the programmer +reasonable behavior, the +\fIlongjmp\fR() +function has to call all cancellation cleanup handlers that have been +pushed but not popped since the time +\fIsetjmp\fR() +was called. +.P +Consider a multi-threaded function called by a thread that uses +signals. If a signal were delivered to a signal handler during the +operation of +\fIqsort\fR() +and that handler were to call +\fIlongjmp\fR() +(which, in turn, did +.IR not +call the cancellation cleanup handlers) the helper threads created by +the +\fIqsort\fR() +function would not be canceled. Instead, they would continue to execute +and write into the argument array even though the array might have been +popped off the stack. +.P +Note that the specified cleanup handling mechanism is especially tied +to the C language and, while the requirement for a uniform mechanism +for expressing cleanup is language-independent, the mechanism used in +other languages may be quite different. In addition, this mechanism is +really only necessary due to the lack of a real exception mechanism in +the C language, which would be the ideal solution. +.P +There is no notion of a cancellation cleanup-safe function. If an +application has no cancellation points in its signal handlers, blocks +any signal whose handler may have cancellation points while calling +async-unsafe functions, or disables cancellation while calling +async-unsafe functions, all functions may be safely called from +cancellation cleanup routines. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cancel\fR\^(\|)", +.IR "\fIpthread_setcancelstate\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_cond_broadcast.3p b/upstream/archlinux/man3p/pthread_cond_broadcast.3p new file mode 100644 index 00000000..c7c1320a --- /dev/null +++ b/upstream/archlinux/man3p/pthread_cond_broadcast.3p @@ -0,0 +1,240 @@ +'\" et +.TH PTHREAD_COND_BROADCAST "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_cond_broadcast, +pthread_cond_signal +\(em broadcast or signal a condition +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_broadcast(pthread_cond_t *\fIcond\fP); +int pthread_cond_signal(pthread_cond_t *\fIcond\fP); +.fi +.SH DESCRIPTION +These functions shall unblock threads blocked on a condition variable. +.P +The +\fIpthread_cond_broadcast\fR() +function shall unblock all threads currently blocked on the specified +condition variable +.IR cond . +.P +The +\fIpthread_cond_signal\fR() +function shall unblock at least one of the threads that are blocked +on the specified condition variable +.IR cond +(if any threads are blocked on +.IR cond ). +.P +If more than one thread is blocked on a condition variable, the +scheduling policy shall determine the order in which threads are +unblocked. When each thread unblocked as a result of a +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +returns from its call to +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR(), +the thread shall own the mutex with which it called +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR(). +The thread(s) that are unblocked shall contend for the mutex according +to the scheduling policy (if applicable), and as if each had called +\fIpthread_mutex_lock\fR(). +.P +The +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +functions may be called by a thread whether or not it currently owns +the mutex that threads calling +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR() +have associated with the condition variable during their waits; +however, if predictable scheduling behavior is required, then that +mutex shall be locked by the thread calling +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR(). +.P +The +\fIpthread_cond_broadcast\fR() +and +\fIpthread_cond_signal\fR() +functions shall have no effect if there are no threads currently +blocked on +.IR cond . +.P +The behavior is undefined if the value specified by the +.IR cond +argument to +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +does not refer to an initialized condition variable. +.SH "RETURN VALUE" +If successful, the +\fIpthread_cond_broadcast\fR() +and +\fIpthread_cond_signal\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_cond_broadcast\fR() +function is used whenever the shared-variable state has been changed in +a way that more than one thread can proceed with its task. Consider a +single producer/multiple consumer problem, where the producer can +insert multiple items on a list that is accessed one item at a time by +the consumers. By calling the +\fIpthread_cond_broadcast\fR() +function, the producer would notify all consumers that might be +waiting, and thereby the application would receive more throughput on a +multi-processor. In addition, +\fIpthread_cond_broadcast\fR() +makes it easier to implement a read-write lock. The +\fIpthread_cond_broadcast\fR() +function is needed in order to wake up all waiting readers when a +writer releases its lock. Finally, the two-phase commit algorithm can +use this broadcast function to notify all clients of an impending +transaction commit. +.P +It is not safe to use the +\fIpthread_cond_signal\fR() +function in a signal handler that is invoked asynchronously. Even if +it were safe, there would still be a race between the test of the +Boolean +\fIpthread_cond_wait\fR() +that could not be efficiently eliminated. +.P +Mutexes and condition variables are thus not suitable for releasing a +waiting thread by signaling from code running in a signal handler. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +does not refer to an initialized condition variable, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.SS "Multiple Awakenings by Condition Signal" +.P +On a multi-processor, it may be impossible for an implementation of +\fIpthread_cond_signal\fR() +to avoid the unblocking of more than one thread blocked on a condition +variable. For example, consider the following partial implementation +of +\fIpthread_cond_wait\fR() +and +\fIpthread_cond_signal\fR(), +executed by two threads in the order given. One thread is trying to +wait on the condition variable, another is concurrently executing +\fIpthread_cond_signal\fR(), +while a third thread is already waiting. +.sp +.RS 4 +.nf + +pthread_cond_wait(mutex, cond): + value = cond->value; /* 1 */ + pthread_mutex_unlock(mutex); /* 2 */ + pthread_mutex_lock(cond->mutex); /* 10 */ + if (value == cond->value) { /* 11 */ + me->next_cond = cond->waiter; + cond->waiter = me; + pthread_mutex_unlock(cond->mutex); + unable_to_run(me); + } else + pthread_mutex_unlock(cond->mutex); /* 12 */ + pthread_mutex_lock(mutex); /* 13 */ +.P +pthread_cond_signal(cond): + pthread_mutex_lock(cond->mutex); /* 3 */ + cond->value++; /* 4 */ + if (cond->waiter) { /* 5 */ + sleeper = cond->waiter; /* 6 */ + cond->waiter = sleeper->next_cond; /* 7 */ + able_to_run(sleeper); /* 8 */ + } + pthread_mutex_unlock(cond->mutex); /* 9 */ +.fi +.P +.RE +.P +The effect is that more than one thread can return from its call to +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR() +as a result of one call to +\fIpthread_cond_signal\fR(). +This effect is called ``spurious wakeup''. +Note that the situation is self-correcting in that the number of +threads that are so awakened is finite; for example, the next thread to +call +\fIpthread_cond_wait\fR() +after the sequence of events above blocks. +.P +While this problem could be resolved, the loss of efficiency for a +fringe condition that occurs only rarely is unacceptable, especially +given that one has to check the predicate associated with a condition +variable anyway. Correcting this problem would unnecessarily reduce +the degree of concurrency in this basic building block for all +higher-level synchronization operations. +.P +An added benefit of allowing spurious wakeups is that applications are +forced to code a predicate-testing-loop around the condition wait. +This also makes the application tolerate superfluous condition +broadcasts or signals on the same condition variable that may be coded +in some other part of the application. The resulting applications are +thus more robust. Therefore, POSIX.1\(hy2008 explicitly documents that +spurious wakeups may occur. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_cond_destroy.3p b/upstream/archlinux/man3p/pthread_cond_destroy.3p new file mode 100644 index 00000000..50bf6560 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_cond_destroy.3p @@ -0,0 +1,228 @@ +'\" et +.TH PTHREAD_COND_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_cond_destroy, +pthread_cond_init +\(em destroy and initialize condition variables +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_destroy(pthread_cond_t *\fIcond\fP); +int pthread_cond_init(pthread_cond_t *restrict \fIcond\fP, + const pthread_condattr_t *restrict \fIattr\fP); +pthread_cond_t \fIcond\fP = PTHREAD_COND_INITIALIZER; +.fi +.SH DESCRIPTION +The +\fIpthread_cond_destroy\fR() +function shall destroy the given condition variable specified by +.IR cond ; +the object becomes, in effect, uninitialized. An implementation may +cause +\fIpthread_cond_destroy\fR() +to set the object referenced by +.IR cond +to an invalid value. A destroyed condition variable object can be +reinitialized using +\fIpthread_cond_init\fR(); +the results of otherwise referencing the object after it has been +destroyed are undefined. +.P +It shall be safe to destroy an initialized condition variable upon which +no threads are currently blocked. Attempting to destroy a condition +variable upon which other threads are currently blocked results in +undefined behavior. +.P +The +\fIpthread_cond_init\fR() +function shall initialize the condition variable referenced by +.IR cond +with attributes referenced by +.IR attr . +If +.IR attr +is NULL, the default condition variable attributes shall be used; the +effect is the same as passing the address of a default condition +variable attributes object. Upon successful initialization, the state +of the condition variable shall become initialized. +.P +See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. +.P +Attempting to initialize an already initialized condition variable +results in undefined behavior. +.P +In cases where default condition variable attributes are appropriate, +the macro PTHREAD_COND_INITIALIZER can be used to initialize condition +variables. The effect shall be equivalent to dynamic initialization by +a call to +\fIpthread_cond_init\fR() +with parameter +.IR attr +specified as NULL, except that no error checks are performed. +.P +The behavior is undefined if the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +does not refer to an initialized condition variable. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_cond_init\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_cond_destroy\fR() +and +\fIpthread_cond_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_cond_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources (other than memory) to +initialize another condition variable. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the condition variable. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +A condition variable can be destroyed immediately after all the threads +that are blocked on it are awakened. For example, consider the +following code: +.sp +.RS 4 +.nf + +struct list { + pthread_mutex_t lm; + ... +} +.P +struct elt { + key k; + int busy; + pthread_cond_t notbusy; + ... +} +.P +/* Find a list element and reserve it. */ +struct elt * +list_find(struct list *lp, key k) +{ + struct elt *ep; +.P + pthread_mutex_lock(&lp->lm); + while ((ep = find_elt(l, k) != NULL) && ep->busy) + pthread_cond_wait(&ep->notbusy, &lp->lm); + if (ep != NULL) + ep->busy = 1; + pthread_mutex_unlock(&lp->lm); + return(ep); +} +.P +delete_elt(struct list *lp, struct elt *ep) +{ + pthread_mutex_lock(&lp->lm); + assert(ep->busy); + ... remove ep from list ... + ep->busy = 0; /* Paranoid. */ +(A) pthread_cond_broadcast(&ep->notbusy); + pthread_mutex_unlock(&lp->lm); +(B) pthread_cond_destroy(&ep->notbusy); + free(ep); +} +.fi +.P +.RE +.P +In this example, the condition variable and its list element may be +freed (line B) immediately after all threads waiting for it are +awakened (line A), since the mutex and the code ensure that no other +thread can touch the element to be deleted. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +does not refer to an initialized condition variable, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_destroy\fR() +or +\fIpthread_cond_init\fR() +refers to a condition variable that is in use (for example, in a +\fIpthread_cond_wait\fR() +call) by another thread, or detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_init\fR() +refers to an already initialized condition variable, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_cond_init\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See also +.IR "\fIpthread_mutex_destroy\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_broadcast\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_cond_signal.3p b/upstream/archlinux/man3p/pthread_cond_signal.3p new file mode 100644 index 00000000..4c946f6e --- /dev/null +++ b/upstream/archlinux/man3p/pthread_cond_signal.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_COND_SIGNAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_cond_signal +\(em signal a condition +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_signal(pthread_cond_t *\fIcond\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_cond_broadcast\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_cond_timedwait.3p b/upstream/archlinux/man3p/pthread_cond_timedwait.3p new file mode 100644 index 00000000..6778468c --- /dev/null +++ b/upstream/archlinux/man3p/pthread_cond_timedwait.3p @@ -0,0 +1,464 @@ +'\" et +.TH PTHREAD_COND_TIMEDWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_cond_timedwait, +pthread_cond_wait +\(em wait on a condition +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_cond_timedwait(pthread_cond_t *restrict \fIcond\fP, + pthread_mutex_t *restrict \fImutex\fP, + const struct timespec *restrict \fIabstime\fP); +int pthread_cond_wait(pthread_cond_t *restrict \fIcond\fP, + pthread_mutex_t *restrict \fImutex\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_cond_timedwait\fR() +and +\fIpthread_cond_wait\fR() +functions shall block on a condition variable. The application shall +ensure that these functions are called with +.IR mutex +locked by the calling thread; otherwise, an error (for +PTHREAD_MUTEX_ERRORCHECK and robust mutexes) or undefined behavior +(for other mutexes) results. +.P +These functions atomically release +.IR mutex +and cause the calling thread to block on the condition variable +.IR cond ; +atomically here means ``atomically with respect to access by another +thread to the mutex and then the condition variable''. That is, if +another thread is able to acquire the mutex after the about-to-block +thread has released it, then a subsequent call to +\fIpthread_cond_broadcast\fR() +or +\fIpthread_cond_signal\fR() +in that thread shall behave as if it were issued after the +about-to-block thread has blocked. +.P +Upon successful return, the mutex shall have been locked and shall be +owned by the calling thread. If +.IR mutex +is a robust mutex where an owner terminated while holding the lock and +the state is recoverable, the mutex shall be acquired even though the +function returns an error code. +.P +When using condition variables there is always a Boolean predicate +involving shared variables associated with each condition wait that is +true if the thread should proceed. Spurious wakeups from the +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +functions may occur. Since the return from +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +does not imply anything about the value of this predicate, the +predicate should be re-evaluated upon such return. +.P +When a thread waits on a condition variable, having specified a +particular mutex to either the +\fIpthread_cond_timedwait\fR() +or the +\fIpthread_cond_wait\fR() +operation, a dynamic binding is formed between that mutex and condition +variable that remains in effect as long as at least one thread is +blocked on the condition variable. During this time, the effect of an +attempt by any thread to wait on that condition variable using a +different mutex is undefined. Once all waiting threads have been +unblocked (as by the +\fIpthread_cond_broadcast\fR() +operation), the next wait operation on that condition variable shall +form a new dynamic binding with the mutex specified by that wait +operation. Even though the dynamic binding between condition variable +and mutex may be removed or replaced between the time a thread is +unblocked from a wait on the condition variable and the time that it +returns to the caller or begins cancellation cleanup, the unblocked +thread shall always re-acquire the mutex specified in the condition +wait operation call from which it is returning. +.P +A condition wait (whether timed or not) is a cancellation point. When +the cancelability type of a thread is set to PTHREAD_CANCEL_DEFERRED, +a side-effect of acting upon a cancellation request while in a +condition wait is that the mutex is (in effect) re-acquired before +calling the first cancellation cleanup handler. The effect is as if +the thread were unblocked, allowed to execute up to the point of +returning from the call to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR(), +but at that point notices the cancellation request and instead of +returning to the caller of +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR(), +starts the thread cancellation activities, which includes calling +cancellation cleanup handlers. +.P +A thread that has been unblocked because it has been canceled while +blocked in a call to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +shall not consume any condition signal that may be directed concurrently +at the condition variable if there are other threads blocked on the +condition variable. +.P +The +\fIpthread_cond_timedwait\fR() +function shall be equivalent to +\fIpthread_cond_wait\fR(), +except that an error is returned if the absolute time specified by +.IR abstime +passes (that is, system time equals or exceeds +.IR abstime ) +before the condition +.IR cond +is signaled or broadcasted, or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. When such timeouts +occur, +\fIpthread_cond_timedwait\fR() +shall nonetheless release and re-acquire the mutex referenced by +.IR mutex , +and may consume a condition signal directed concurrently at the condition +variable. +.P +The condition variable shall have a clock attribute which specifies +the clock that shall be used to measure the time specified by the +.IR abstime +argument. The +\fIpthread_cond_timedwait\fR() +function is also a cancellation point. +.P +If a signal is delivered to a thread waiting for a condition variable, +upon return from the signal handler the thread resumes waiting for the +condition variable as if it was not interrupted, or it shall return +zero due to spurious wakeup. +.P +The behavior is undefined if the value specified by the +.IR cond +or +.IR mutex +argument to these functions does not refer to an initialized +condition variable or an initialized mutex object, respectively. +.SH "RETURN VALUE" +Except for +.BR [ETIMEDOUT] , +.BR [ENOTRECOVERABLE] , +and +.BR [EOWNERDEAD] , +all these error checks shall act as if they were performed immediately +at the beginning of processing for the function and shall cause an +error return, in effect, prior to modifying the state of the mutex +specified by +.IR mutex +or the condition variable specified by +.IR cond . +.P +Upon successful completion, a value of zero shall be returned; otherwise, +an error number shall be returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR ENOTRECOVERABLE +.br +The state protected by the mutex is not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent. +.TP +.BR EPERM +The mutex type is PTHREAD_MUTEX_ERRORCHECK or the mutex +is a robust mutex, and the current thread does not own the mutex. +.P +The +\fIpthread_cond_timedwait\fR() +function shall fail if: +.TP +.BR ETIMEDOUT +The time specified by +.IR abstime +to +\fIpthread_cond_timedwait\fR() +has passed. +.TP +.BR EINVAL +The +.IR abstime +argument specified a nanosecond value less than zero or greater than +or equal to 1000 million. +.br +.P +These functions may fail if: +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state consistent. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications that have assumed that non-zero return values are errors +will need updating for use with robust mutexes, since a valid return +for a thread acquiring a mutex which is protecting a currently +inconsistent state is +.BR [EOWNERDEAD] . +Applications that do not check the error returns, due to ruling out the +possibility of such errors arising, should not use robust mutexes. If +an application is supposed to work with normal and robust mutexes, it +should check all return values for error conditions and if necessary +take appropriate action. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR cond +argument to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +does not refer to an initialized condition variable, or detects that +the value specified by the +.IR mutex +argument to +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +does not refer to an initialized mutex object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.SS "Condition Wait Semantics" +.P +It is important to note that when +\fIpthread_cond_wait\fR() +and +\fIpthread_cond_timedwait\fR() +return without error, the associated predicate may still be false. +Similarly, when +\fIpthread_cond_timedwait\fR() +returns with the timeout error, the associated predicate may be true +due to an unavoidable race between the expiration of the timeout and +the predicate state change. +.P +The application needs to recheck the predicate on any return because it +cannot be sure there is another thread waiting on the thread to handle +the signal, and if there is not then the signal is lost. The burden is +on the application to check the predicate. +.P +Some implementations, particularly on a multi-processor, may sometimes +cause multiple threads to wake up when the condition variable is +signaled simultaneously on different processors. +.P +In general, whenever a condition wait returns, the thread has to +re-evaluate the predicate associated with the condition wait to +determine whether it can safely proceed, should wait again, or should +declare a timeout. A return from the wait does not imply that the +associated predicate is either true or false. +.P +It is thus recommended that a condition wait be enclosed in the +equivalent of a ``while loop'' that checks the predicate. +.SS "Timed Wait Semantics" +.P +An absolute time measure was chosen for specifying the timeout +parameter for two reasons. First, a relative time measure can be +easily implemented on top of a function that specifies absolute time, +but there is a race condition associated with specifying an absolute +timeout on top of a function that specifies relative timeouts. For +example, assume that +\fIclock_gettime\fR() +returns the current time and +\fIcond_relative_timed_wait\fR() +uses relative timeouts: +.sp +.RS 4 +.nf + +clock_gettime(CLOCK_REALTIME, &now) +reltime = sleep_til_this_absolute_time -now; +cond_relative_timed_wait(c, m, &reltime); +.fi +.P +.RE +.P +If the thread is preempted between the first statement and the last +statement, +the thread blocks for too long. Blocking, however, is irrelevant if an +absolute timeout is used. An absolute timeout also need not be +recomputed if it is used multiple times in a loop, such as that +enclosing a condition wait. +.P +For cases when the system clock is advanced discontinuously by an +operator, it is expected that implementations process any timed wait +expiring at an intervening time as if that time had actually occurred. +.SS "Cancellation and Condition Wait" +.P +A condition wait, whether timed or not, is a cancellation point. That +is, the functions +\fIpthread_cond_wait\fR() +or +\fIpthread_cond_timedwait\fR() +are points where a pending (or concurrent) cancellation request is +noticed. The reason for this is that an indefinite wait is possible at +these points\(emwhatever event is being waited for, even if the program +is totally correct, might never occur; for example, some input data +being awaited might never be sent. By making condition wait a +cancellation point, the thread can be canceled and perform its +cancellation cleanup handler even though it may be stuck in some +indefinite wait. +.P +A side-effect of acting on a cancellation request while a thread is +blocked on a condition variable is to re-acquire the mutex before +calling any of the cancellation cleanup handlers. This is done in order +to ensure that the cancellation cleanup handler is executed in the same +state as the critical code that lies both before and after the call to +the condition wait function. This rule is also required when +interfacing to POSIX threads from languages, such as Ada or C++, which +may choose to map cancellation onto a language exception; this rule +ensures that each exception handler guarding a critical section can +always safely depend upon the fact that the associated mutex has +already been locked regardless of exactly where within the critical +section the exception was raised. Without this rule, there would not be +a uniform rule that exception handlers could follow regarding the lock, +and so coding would become very cumbersome. +.P +Therefore, since +.IR some +statement has to be made regarding the state of the lock when a +cancellation is delivered during a wait, a definition has been chosen +that makes application coding most convenient and error free. +.P +When acting on a cancellation request while a thread is blocked on a +condition variable, the implementation is required to ensure that the +thread does not consume any condition signals directed at that +condition variable if there are any other threads waiting on that +condition variable. This rule is specified in order to avoid deadlock +conditions that could occur if these two independent requests (one +acting on a thread and the other acting on the condition variable) were +not processed independently. +.SS "Performance of Mutexes and Condition Variables" +.P +Mutexes are expected to be locked only for a few instructions. This +practice is almost automatically enforced by the desire of programmers +to avoid long serial regions of execution (which would reduce total +effective parallelism). +.P +When using mutexes and condition variables, one tries to ensure that +the usual case is to lock the mutex, access shared data, and unlock the +mutex. Waiting on a condition variable should be a relatively rare +situation. For example, when implementing a read-write lock, code +that acquires a read-lock typically needs only to increment the count +of readers (under mutual-exclusion) and return. The calling thread +would actually wait on the condition variable only when there is +already an active writer. So the efficiency of a synchronization +operation is bounded by the cost of mutex lock/unlock and not by +condition wait. Note that in the usual case there is no context +switch. +.P +This is not to say that the efficiency of condition waiting is +unimportant. Since there needs to be at least one context switch per +Ada rendezvous, the efficiency of waiting on a condition variable is +important. The cost of waiting on a condition variable should be +little more than the minimal cost for a context switch plus the time to +unlock and lock the mutex. +.SS "Features of Mutexes and Condition Variables" +.P +It had been suggested that the mutex acquisition and release be +decoupled from condition wait. This was rejected because it is the +combined nature of the operation that, in fact, facilitates realtime +implementations. Those implementations can atomically move a +high-priority thread between the condition variable and the mutex in a +manner that is transparent to the caller. This can prevent extra +context switches and provide more deterministic acquisition of a mutex +when the waiting thread is signaled. Thus, fairness and priority +issues can be dealt with directly by the scheduling discipline. +Furthermore, the current condition wait operation matches existing +practice. +.SS "Scheduling Behavior of Mutexes and Condition Variables" +.P +Synchronization primitives that attempt to interfere with scheduling +policy by specifying an ordering rule are considered undesirable. +Threads waiting on mutexes and condition variables are selected to +proceed in an order dependent upon the scheduling policy rather than in +some fixed order (for example, FIFO or priority). Thus, the scheduling +policy determines which thread(s) are awakened and allowed to proceed. +.SS "Timed Condition Wait" +.P +The +\fIpthread_cond_timedwait\fR() +function allows an application to give up waiting for a particular +condition after a given amount of time. An example of its use +follows: +.sp +.RS 4 +.nf + +(void) pthread_mutex_lock(&t.mn); + t.waiters++; + clock_gettime(CLOCK_REALTIME, &ts); + ts.tv_sec += 5; + rc = 0; + while (! mypredicate(&t) && rc == 0) + rc = pthread_cond_timedwait(&t.cond, &t.mn, &ts); + t.waiters--; + if (rc == 0 || mypredicate(&t)) + setmystate(&t); +(void) pthread_mutex_unlock(&t.mn); +.fi +.P +.RE +.P +By making the timeout parameter absolute, it does not need to be +recomputed each time the program checks its blocking predicate. If the +timeout was relative, it would have to be recomputed before each call. +This would be especially difficult since such code would need to take +into account the possibility of extra wakeups that result from extra +broadcasts or signals on the condition variable that occur before +either the predicate is true or the timeout is due. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_broadcast\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_condattr_destroy.3p b/upstream/archlinux/man3p/pthread_condattr_destroy.3p new file mode 100644 index 00000000..9c38e85c --- /dev/null +++ b/upstream/archlinux/man3p/pthread_condattr_destroy.3p @@ -0,0 +1,143 @@ +'\" et +.TH PTHREAD_CONDATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_condattr_destroy, +pthread_condattr_init +\(em destroy and initialize the condition variable attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_destroy(pthread_condattr_t *\fIattr\fP); +int pthread_condattr_init(pthread_condattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_condattr_destroy\fR() +function shall destroy a condition variable attributes object; the +object becomes, in effect, uninitialized. An implementation may cause +\fIpthread_condattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_condattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIpthread_condattr_init\fR() +function shall initialize a condition variable attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +Results are undefined if +\fIpthread_condattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +After a condition variable attributes object has been used to +initialize one or more condition variables, any function affecting the +attributes object (including destruction) shall not affect any +previously initialized condition variables. +.P +This volume of POSIX.1\(hy2017 requires two attributes, the +.IR clock +attribute and the +.IR process-shared +attribute. +.P +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_condattr_destroy\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_condattr_destroy\fR() +and +\fIpthread_condattr_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_condattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the condition variable +attributes object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +A +.IR process-shared +attribute has been defined for condition variables for the same reason +it has been defined for mutexes. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_condattr_destroy\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See also +.IR "\fIpthread_attr_destroy\fR\^(\|)" +and +.IR "\fIpthread_mutex_destroy\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_attr_destroy\fR\^(\|)", +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_getpshared\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_condattr_getclock.3p b/upstream/archlinux/man3p/pthread_condattr_getclock.3p new file mode 100644 index 00000000..dacf126b --- /dev/null +++ b/upstream/archlinux/man3p/pthread_condattr_getclock.3p @@ -0,0 +1,135 @@ +'\" et +.TH PTHREAD_CONDATTR_GETCLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_condattr_getclock, +pthread_condattr_setclock +\(em get and set the clock selection condition variable attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_getclock(const pthread_condattr_t *restrict \fIattr\fP, + clockid_t *restrict \fIclock_id\fP); +int pthread_condattr_setclock(pthread_condattr_t *\fIattr\fP, + clockid_t \fIclock_id\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_condattr_getclock\fR() +function shall obtain the value of the +.IR clock +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIpthread_condattr_setclock\fR() +function shall set the +.IR clock +attribute in an initialized attributes object referenced by +.IR attr . +If +\fIpthread_condattr_setclock\fR() +is called with a +.IR clock_id +argument that refers to a CPU-time clock, the call shall fail. +.P +The +.IR clock +attribute is the clock ID of the clock that shall be used to +measure the timeout service of +\fIpthread_cond_timedwait\fR(). +The default value of the +.IR clock +attribute shall refer to the system clock. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_condattr_getclock\fR() +or +\fIpthread_condattr_setclock\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_condattr_getclock\fR() +function shall return zero and store the value of the clock attribute +of +.IR attr +into the object referenced by the +.IR clock_id +argument. Otherwise, an error number shall be returned to indicate the +error. +.P +If successful, the +\fIpthread_condattr_setclock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_condattr_setclock\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR clock_id +does not refer to a known clock, or is a CPU-time clock. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_condattr_getclock\fR() +or +\fIpthread_condattr_setclock\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_condattr_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_getpshared\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_condattr_getpshared.3p b/upstream/archlinux/man3p/pthread_condattr_getpshared.3p new file mode 100644 index 00000000..d7f72d7f --- /dev/null +++ b/upstream/archlinux/man3p/pthread_condattr_getpshared.3p @@ -0,0 +1,130 @@ +'\" et +.TH PTHREAD_CONDATTR_GETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_condattr_getpshared, +pthread_condattr_setpshared +\(em get and set the process-shared condition variable attributes +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_getpshared(const pthread_condattr_t *restrict \fIattr\fP, + int *restrict \fIpshared\fP); +int pthread_condattr_setpshared(pthread_condattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_condattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIpthread_condattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute is set to PTHREAD_PROCESS_SHARED +to permit a condition variable to be operated upon by any thread that +has access to the memory where the condition variable is allocated, +even if the condition variable is allocated in memory that is shared by +multiple processes. See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. The default value of the attribute +is PTHREAD_PROCESS_PRIVATE. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_condattr_getpshared\fR() +or +\fIpthread_condattr_setpshared\fR() +does not refer to an initialized condition variable attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_condattr_setpshared\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.P +If successful, the +\fIpthread_condattr_getpshared\fR() +function shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate the +error. +.SH ERRORS +The +\fIpthread_condattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the attribute is outside the range of legal +values for that attribute. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_condattr_getpshared\fR() +or +\fIpthread_condattr_setpshared\fR() +does not refer to an initialized condition variable attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_condattr_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_condattr_init.3p b/upstream/archlinux/man3p/pthread_condattr_init.3p new file mode 100644 index 00000000..cb6fc8ce --- /dev/null +++ b/upstream/archlinux/man3p/pthread_condattr_init.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_CONDATTR_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_condattr_init +\(em initialize the condition variable attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_init(pthread_condattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_condattr_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_condattr_setclock.3p b/upstream/archlinux/man3p/pthread_condattr_setclock.3p new file mode 100644 index 00000000..cde8423f --- /dev/null +++ b/upstream/archlinux/man3p/pthread_condattr_setclock.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_CONDATTR_SETCLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_condattr_setclock +\(em set the clock selection condition variable attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_setclock(pthread_condattr_t *\fIattr\fP, + clockid_t \fIclock_id\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_condattr_getclock\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_condattr_setpshared.3p b/upstream/archlinux/man3p/pthread_condattr_setpshared.3p new file mode 100644 index 00000000..65ea65a7 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_condattr_setpshared.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_CONDATTR_SETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_condattr_setpshared +\(em set the process-shared condition variable attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_condattr_setpshared(pthread_condattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_condattr_getpshared\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_create.3p b/upstream/archlinux/man3p/pthread_create.3p new file mode 100644 index 00000000..c46aa12a --- /dev/null +++ b/upstream/archlinux/man3p/pthread_create.3p @@ -0,0 +1,238 @@ +'\" et +.TH PTHREAD_CREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_create +\(em thread creation +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_create(pthread_t *restrict \fIthread\fP, + const pthread_attr_t *restrict \fIattr\fP, + void *(*\fIstart_routine\fP)(void*), void *restrict \fIarg\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_create\fR() +function shall create a new thread, with attributes specified by +.IR attr , +within a process. If +.IR attr +is NULL, the default attributes shall be used. If the attributes +specified by +.IR attr +are modified later, the thread's attributes shall not be affected. +Upon successful completion, +\fIpthread_create\fR() +shall store the ID of the created thread in the location referenced by +.IR thread . +.P +The thread is created executing +.IR start_routine +with +.IR arg +as its sole argument. If the +.IR start_routine +returns, the effect shall be as if there was an implicit call to +\fIpthread_exit\fR() +using the return value of +.IR start_routine +as the exit status. Note that the thread in which +\fImain\fR() +was originally invoked differs from this. When it returns from +\fImain\fR(), +the effect shall be as if there was an implicit call to +\fIexit\fR() +using the return value of +\fImain\fR() +as the exit status. +.P +The signal state of the new thread shall be initialized as follows: +.IP " *" 4 +The signal mask shall be inherited from the creating thread. +.IP " *" 4 +The set of signals pending for the new thread shall be empty. +.P +The thread-local current locale +and the alternate stack +shall not be inherited. +.P +The floating-point environment shall be inherited from the creating +thread. +.P +If +\fIpthread_create\fR() +fails, no new thread is created and the contents of the location +referenced by +.IR thread +are undefined. +.P +If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a +CPU-time clock accessible, and the initial value of this clock shall +be set to zero. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_create\fR() +does not refer to an initialized thread attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_create\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_create\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources to create another thread, or +the system-imposed limit on the total number of threads in a process +{PTHREAD_THREADS_MAX} +would be exceeded. +.TP +.BR EPERM +The caller does not have appropriate privileges to set the required +scheduling parameters or scheduling policy. +.P +The +\fIpthread_create\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +There is no requirement on the implementation that the ID of the +created thread be available before the newly created thread starts +executing. The calling thread can obtain the ID of the created thread +through the +.IR thread +argument of the +\fIpthread_create\fR() +function, and the newly created thread can obtain its ID by a call to +\fIpthread_self\fR(). +.SH RATIONALE +A suggested alternative to +\fIpthread_create\fR() +would be to define two separate operations: create and start. Some +applications would find such behavior more natural. Ada, in +particular, separates the ``creation'' of a task from its +``activation''. +.P +Splitting the operation was rejected by the standard developers for +many reasons: +.IP " *" 4 +The number of calls required to start a thread would increase from one +to two and thus place an additional burden on applications that do not +require the additional synchronization. The second call, however, +could be avoided by the additional complication of a start-up state +attribute. +.IP " *" 4 +An extra state would be introduced: ``created but not started''. This +would require the standard to specify the behavior of the thread +operations when the target has not yet started executing. +.IP " *" 4 +For those applications that require such behavior, it is possible to +simulate the two separate steps with the facilities that are currently +provided. The +\fIstart_routine\fR() +can synchronize by waiting on a condition variable that is signaled by +the start operation. +.P +An Ada implementor can choose to create the thread at either of two +points in the Ada program: when the task object is created, or when +the task is activated (generally at a ``begin''). If the first +approach is adopted, the +\fIstart_routine\fR() +needs to wait on a condition variable to receive the order to begin +``activation''. The second approach requires no such condition +variable or extra synchronization. In either approach, a separate Ada +task control block would need to be created when the task object is +created to hold rendezvous queues, and so on. +.P +An extension of the preceding model would be to allow the state of the +thread to be modified between the create and start. This would allow +the thread attributes object to be eliminated. This has been rejected +because: +.IP " *" 4 +All state in the thread attributes object has to be able to be set for +the thread. This would require the definition of functions to modify +thread attributes. There would be no reduction in the number of +function calls required to set up the thread. In fact, for an +application that creates all threads using identical attributes, the +number of function calls required to set up the threads would be +dramatically increased. Use of a thread attributes object permits the +application to make one set of attribute setting function calls. +Otherwise, the set of attribute setting function calls needs to be made +for each thread creation. +.IP " *" 4 +Depending on the implementation architecture, functions to set thread +state would require kernel calls, or for other implementation reasons +would not be able to be implemented as macros, thereby increasing the +cost of thread creation. +.IP " *" 4 +The ability for applications to segregate threads by class would be +lost. +.P +Another suggested alternative uses a model similar to that for process +creation, such as ``thread fork''. The fork semantics would provide +more flexibility and the ``create'' function can be implemented simply +by doing a thread fork followed immediately by a call to the desired +``start routine'' for the thread. This alternative has these +problems: +.IP " *" 4 +For many implementations, the entire stack of the calling thread would +need to be duplicated, since in many architectures there is no way to +determine the size of the calling frame. +.IP " *" 4 +Efficiency is reduced since at least some part of the stack has to be +copied, even though in most cases the thread never needs the copied +context, since it merely calls the desired start routine. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_create\fR() +does not refer to an initialized thread attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfork\fR\^(\|)", +.IR "\fIpthread_exit\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_detach.3p b/upstream/archlinux/man3p/pthread_detach.3p new file mode 100644 index 00000000..e0f661e9 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_detach.3p @@ -0,0 +1,121 @@ +'\" et +.TH PTHREAD_DETACH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_detach +\(em detach a thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_detach(pthread_t \fIthread\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_detach\fR() +function shall indicate to the implementation that storage for the +thread +.IR thread +can be reclaimed when that thread terminates. If +.IR thread +has not terminated, +\fIpthread_detach\fR() +shall not cause it to terminate. +.P +The behavior is undefined if the value specified by the +.IR thread +argument to +\fIpthread_detach\fR() +does not refer to a joinable thread. +.SH "RETURN VALUE" +If the call succeeds, +\fIpthread_detach\fR() +shall return 0; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_detach\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_join\fR() +or +\fIpthread_detach\fR() +functions should eventually be called for every thread that is created +so that storage associated with the thread may be reclaimed. +.P +It has been suggested that a ``detach'' function is not necessary; the +.IR detachstate +thread creation attribute is sufficient, since a thread need never be +dynamically detached. However, need arises in at least two cases: +.IP " 1." 4 +In a cancellation handler for a +\fIpthread_join\fR() +it is nearly essential to have a +\fIpthread_detach\fR() +function in order to detach the thread on which +\fIpthread_join\fR() +was waiting. Without it, it would be necessary to have the handler do +another +\fIpthread_join\fR() +to attempt to detach the thread, which would both delay the cancellation +processing for an unbounded period and introduce a new call to +\fIpthread_join\fR(), +which might itself need a cancellation handler. A dynamic detach is +nearly essential in this case. +.IP " 2." 4 +In order to detach the ``initial thread'' (as may be desirable in +processes that set up server threads). +.P +If an implementation detects that the value specified by the +.IR thread +argument to +\fIpthread_detach\fR() +does not refer to a joinable thread, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_join\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_equal.3p b/upstream/archlinux/man3p/pthread_equal.3p new file mode 100644 index 00000000..49b36853 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_equal.3p @@ -0,0 +1,88 @@ +'\" et +.TH PTHREAD_EQUAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_equal +\(em compare thread IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_equal(pthread_t \fIt1\fP, pthread_t \fIt2\fP); +.fi +.SH DESCRIPTION +This function shall compare the thread IDs +.IR t1 +and +.IR t2 . +.SH "RETURN VALUE" +The +\fIpthread_equal\fR() +function shall return a non-zero value if +.IR t1 +and +.IR t2 +are equal; otherwise, zero shall be returned. +.P +If either +.IR t1 +or +.IR t2 +are not valid thread IDs, the behavior is undefined. +.SH ERRORS +No errors are defined. +.P +The +\fIpthread_equal\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Implementations may choose to define a +thread ID as a structure. This allows additional flexibility and +robustness over using an +.BR int . +For example, a thread ID could include a sequence number that allows +detection of ``dangling IDs'' (copies of a thread ID that has been +detached). Since the C language does not support comparison on +structure types, the +\fIpthread_equal\fR() +function is provided to compare thread IDs. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_self\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_exit.3p b/upstream/archlinux/man3p/pthread_exit.3p new file mode 100644 index 00000000..1b24a827 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_exit.3p @@ -0,0 +1,129 @@ +'\" et +.TH PTHREAD_EXIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_exit +\(em thread termination +.SH SYNOPSIS +.LP +.nf +#include +.P +void pthread_exit(void *\fIvalue_ptr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_exit\fR() +function shall terminate the calling thread and make the value +.IR value_ptr +available to any successful join with the terminating thread. Any +cancellation cleanup handlers that have been pushed and not yet popped +shall be popped in the reverse order that they were pushed and then +executed. After all cancellation cleanup handlers have been executed, +if the thread has any thread-specific data, appropriate destructor +functions shall be called in an unspecified order. Thread termination +does not release any application visible process resources, including, +but not limited to, mutexes and file descriptors, nor does it perform +any process-level cleanup actions, including, but not limited to, +calling any +\fIatexit\fR() +routines that may exist. +.P +An implicit call to +\fIpthread_exit\fR() +is made when a thread other than the thread in which +\fImain\fR() +was first invoked returns from the start routine that was used to +create it. The function's return value shall serve as the thread's +exit status. +.P +The behavior of +\fIpthread_exit\fR() +is undefined if called from a cancellation cleanup handler or +destructor function that was invoked as a result of either an implicit +or explicit call to +\fIpthread_exit\fR(). +.P +After a thread has terminated, the result of access to local (auto) +variables of the thread is undefined. Thus, references to local +variables of the exiting thread should not be used for the +\fIpthread_exit\fR() +.IR value_ptr +parameter value. +.P +The process shall exit with an exit status of 0 after the last thread +has been terminated. The behavior shall be as if the implementation +called +\fIexit\fR() +with a zero argument at thread termination time. +.SH "RETURN VALUE" +The +\fIpthread_exit\fR() +function cannot return to its caller. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The normal mechanism by which a thread terminates is to return from the +routine that was specified in the +\fIpthread_create\fR() +call that started it. The +\fIpthread_exit\fR() +function provides the capability for a thread to terminate without +requiring a return from the start routine of that thread, thereby +providing a function analogous to +\fIexit\fR(). +.P +Regardless of the method of thread termination, any +cancellation cleanup handlers that have been pushed and not yet popped +are executed, and the destructors for any existing thread-specific data +are executed. This volume of POSIX.1\(hy2017 requires that cancellation cleanup handlers be +popped and called in order. After all cancellation cleanup handlers have +been executed, thread-specific data destructors are called, in an +unspecified order, for each item of thread-specific data that exists in +the thread. This ordering is necessary because cancellation cleanup +handlers may rely on thread-specific data. +.P +As the meaning of the status is determined by the application (except +when the thread has been canceled, in which case it is +PTHREAD_CANCELED), +the implementation has no idea what an illegal status value is, which +is why no address error checking is done. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexit\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_join\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_getconcurrency.3p b/upstream/archlinux/man3p/pthread_getconcurrency.3p new file mode 100644 index 00000000..67c640a7 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_getconcurrency.3p @@ -0,0 +1,142 @@ +'\" et +.TH PTHREAD_GETCONCURRENCY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_getconcurrency, +pthread_setconcurrency +\(em get and set the level of concurrency +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_getconcurrency(void); +int pthread_setconcurrency(int \fInew_level\fP); +.fi +.SH DESCRIPTION +Unbound threads in a process may or may not be required to be +simultaneously active. By default, the threads implementation ensures +that a sufficient number of threads are active so that the process can +continue to make progress. While this conserves system resources, it +may not produce the most effective level of concurrency. +.P +The +\fIpthread_setconcurrency\fR() +function allows an application to inform the threads implementation of +its desired concurrency level, +.IR new_level . +The actual level of concurrency provided by the implementation as a +result of this function call is unspecified. +.P +If +.IR new_level +is zero, it causes the implementation to maintain the concurrency level +at its discretion as if +\fIpthread_setconcurrency\fR() +had never been called. +.P +The +\fIpthread_getconcurrency\fR() +function shall return the value set by a previous call to the +\fIpthread_setconcurrency\fR() +function. If the +\fIpthread_setconcurrency\fR() +function was not previously called, this function shall return zero to +indicate that the implementation is maintaining the concurrency level. +.P +A call to +\fIpthread_setconcurrency\fR() +shall inform the implementation of its desired concurrency level. +The implementation shall use this as a hint, not a requirement. +.P +If an implementation does not support multiplexing of user threads on +top of several kernel-scheduled entities, the +\fIpthread_setconcurrency\fR() +and +\fIpthread_getconcurrency\fR() +functions are provided for source code compatibility but they shall +have no effect when called. To maintain the function semantics, the +.IR new_level +parameter is saved when +\fIpthread_setconcurrency\fR() +is called so that a subsequent call to +\fIpthread_getconcurrency\fR() +shall return the same value. +.SH "RETURN VALUE" +If successful, the +\fIpthread_setconcurrency\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_getconcurrency\fR() +function shall always return the concurrency level set by a previous +call to +\fIpthread_setconcurrency\fR(). +If the +\fIpthread_setconcurrency\fR() +function has never been called, +\fIpthread_getconcurrency\fR() +shall return zero. +.SH ERRORS +The +\fIpthread_setconcurrency\fR() +function shall fail if: +.TP +.BR EINVAL +The value specified by +.IR new_level +is negative. +.TP +.BR EAGAIN +The value specified by +.IR new_level +would cause a system resource to be exceeded. +.P +The +\fIpthread_setconcurrency\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Application developers should note that an implementation can always +ignore any calls to +\fIpthread_setconcurrency\fR() +and return a constant for +\fIpthread_getconcurrency\fR(). +For this reason, it is not recommended that portable applications +use this function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_getcpuclockid.3p b/upstream/archlinux/man3p/pthread_getcpuclockid.3p new file mode 100644 index 00000000..6f8b6d01 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_getcpuclockid.3p @@ -0,0 +1,80 @@ +'\" et +.TH PTHREAD_GETCPUCLOCKID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_getcpuclockid +\(em access a thread CPU-time clock +(\fBADVANCED REALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_getcpuclockid(pthread_t \fIthread_id\fP, clockid_t *\fIclock_id\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_getcpuclockid\fR() +function shall return in +.IR clock_id +the clock ID of the CPU-time clock of the thread specified by +.IR thread_id , +if the thread specified by +.IR thread_id +exists. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_getcpuclockid\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_getcpuclockid\fR() +function is part of the Thread CPU-Time Clocks option and need not be +provided on all implementations. +.SH RATIONALE +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getcpuclockid\fR\^(\|)", +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_getschedparam.3p b/upstream/archlinux/man3p/pthread_getschedparam.3p new file mode 100644 index 00000000..d4e35f51 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_getschedparam.3p @@ -0,0 +1,195 @@ +'\" et +.TH PTHREAD_GETSCHEDPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_getschedparam, +pthread_setschedparam +\(em dynamic thread scheduling parameters access +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_getschedparam(pthread_t \fIthread\fP, int *restrict \fIpolicy\fP, + struct sched_param *restrict \fIparam\fP); +int pthread_setschedparam(pthread_t \fIthread\fP, int \fIpolicy\fP, + const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_getschedparam\fR() +and +\fIpthread_setschedparam\fR() +functions shall, respectively, get and set the scheduling policy and +parameters of individual threads within a multi-threaded process to be +retrieved and set. For SCHED_FIFO and SCHED_RR, +the only required member of the +.BR sched_param +structure is the priority +.IR sched_priority . +For SCHED_OTHER, +the affected scheduling parameters are implementation-defined. +.P +The +\fIpthread_getschedparam\fR() +function shall retrieve the scheduling policy and scheduling parameters +for the thread whose thread ID is given by +.IR thread +and shall store those values in +.IR policy +and +.IR param , +respectively. The priority value returned from +\fIpthread_getschedparam\fR() +shall be the value specified by the most recent +\fIpthread_setschedparam\fR(), +\fIpthread_setschedprio\fR(), +or +\fIpthread_create\fR() +call affecting the target thread. It shall not reflect any temporary +adjustments to its priority as a result of any priority inheritance or +ceiling functions. The +\fIpthread_setschedparam\fR() +function shall set the scheduling policy and associated scheduling +parameters for the thread whose thread ID is given by +.IR thread +to the policy and associated parameters provided in +.IR policy +and +.IR param , +respectively. +.P +The +.IR policy +parameter may have the value SCHED_OTHER, SCHED_FIFO, or SCHED_RR. The +scheduling parameters for the SCHED_OTHER policy are +implementation-defined. The SCHED_FIFO and SCHED_RR policies shall +have a single scheduling parameter, +.IR priority . +.P +If _POSIX_THREAD_SPORADIC_SERVER is defined, then the +.IR policy +argument may have the value SCHED_SPORADIC, with the exception for the +\fIpthread_setschedparam\fR() +function that if the scheduling policy was not SCHED_SPORADIC at the +time of the call, it is implementation-defined whether the function +is supported; in other words, the implementation need not allow the +application to dynamically change the scheduling policy to +SCHED_SPORADIC. The sporadic server scheduling policy has the +associated parameters +.IR sched_ss_low_priority , +.IR sched_ss_repl_period , +.IR sched_ss_init_budget , +.IR sched_priority , +and +.IR sched_ss_max_repl . +The specified +.IR sched_ss_repl_period +shall be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,\c +{SS_REPL_MAX}] +for the function to succeed; if not, the function shall fail. +It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +If the +\fIpthread_setschedparam\fR() +function fails, the scheduling parameters shall not be changed +for the target thread. +.SH "RETURN VALUE" +If successful, the +\fIpthread_getschedparam\fR() +and +\fIpthread_setschedparam\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_setschedparam\fR() +function shall fail if: +.TP +.BR ENOTSUP +An attempt was made to set the policy or scheduling parameters to an +unsupported value. +.TP +.BR ENOTSUP +An attempt was made to dynamically change the scheduling policy to +SCHED_SPORADIC, and the implementation does not support this change. +.P +The +\fIpthread_setschedparam\fR() +function may fail if: +.TP +.BR EINVAL +The value specified by +.IR policy +or one of the scheduling parameters associated with the scheduling +policy +.IR policy +is invalid. +.TP +.BR EPERM +The caller does not have appropriate privileges to set either the +scheduling parameters or the scheduling policy of the specified +thread. +.TP +.BR EPERM +The implementation does not allow the application to modify +one of the parameters to the value specified. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_setschedprio\fR\^(\|)", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_getspecific.3p b/upstream/archlinux/man3p/pthread_getspecific.3p new file mode 100644 index 00000000..cde2510b --- /dev/null +++ b/upstream/archlinux/man3p/pthread_getspecific.3p @@ -0,0 +1,153 @@ +'\" et +.TH PTHREAD_GETSPECIFIC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_getspecific, +pthread_setspecific +\(em thread-specific data management +.SH SYNOPSIS +.LP +.nf +#include +.P +void *pthread_getspecific(pthread_key_t \fIkey\fP); +int pthread_setspecific(pthread_key_t \fIkey\fP, const void *\fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_getspecific\fR() +function shall return the value currently bound to the specified +.IR key +on behalf of the calling thread. +.P +The +\fIpthread_setspecific\fR() +function shall associate a thread-specific +.IR value +with a +.IR key +obtained via a previous call to +\fIpthread_key_create\fR(). +Different threads may bind different values to the same key. These +values are typically pointers to blocks of dynamically allocated memory +that have been reserved for use by the calling thread. +.P +The effect of calling +\fIpthread_getspecific\fR() +or +\fIpthread_setspecific\fR() +with a +.IR key +value not obtained from +\fIpthread_key_create\fR() +or after +.IR key +has been deleted with +\fIpthread_key_delete\fR() +is undefined. +.P +Both +\fIpthread_getspecific\fR() +and +\fIpthread_setspecific\fR() +may be called from a thread-specific data destructor function. A call +to +\fIpthread_getspecific\fR() +for the thread-specific data key being destroyed shall return the value +NULL, unless the value is changed (after the destructor starts) by a +call to +\fIpthread_setspecific\fR(). +Calling +\fIpthread_setspecific\fR() +from a thread-specific data destructor routine may result either in lost +storage (after at least PTHREAD_DESTRUCTOR_ITERATIONS attempts at +destruction) or in an infinite loop. +.P +Both functions may be implemented as macros. +.SH "RETURN VALUE" +The +\fIpthread_getspecific\fR() +function shall return the thread-specific data value associated +with the given +.IR key . +If no thread-specific data value is associated with +.IR key , +then the value NULL shall be returned. +.P +If successful, the +\fIpthread_setspecific\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +No errors are returned from +\fIpthread_getspecific\fR(). +.P +The +\fIpthread_setspecific\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to associate the non-NULL value with the key. +.P +The +\fIpthread_setspecific\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Performance and ease-of-use of +\fIpthread_getspecific\fR() +are critical for functions that rely on maintaining state in +thread-specific data. Since no errors are required to be detected by +it, and since the only error that could be detected is the use of an +invalid key, the function to +\fIpthread_getspecific\fR() +has been designed to favor speed and simplicity over error reporting. +.P +If an implementation detects that the value specified by the +.IR key +argument to +\fIpthread_setspecific\fR() +does not refer to a a key value obtained from +\fIpthread_key_create\fR() +or refers to a key that has been deleted with +\fIpthread_key_delete\fR(), +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_key_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_join.3p b/upstream/archlinux/man3p/pthread_join.3p new file mode 100644 index 00000000..9fa3f26d --- /dev/null +++ b/upstream/archlinux/man3p/pthread_join.3p @@ -0,0 +1,232 @@ +'\" et +.TH PTHREAD_JOIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_join +\(em wait for thread termination +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_join(pthread_t \fIthread\fP, void **\fIvalue_ptr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_join\fR() +function shall suspend execution of the calling thread until the target +.IR thread +terminates, unless the target +.IR thread +has already terminated. On return from a successful +\fIpthread_join\fR() +call with a non-NULL +.IR value_ptr +argument, the value passed to +\fIpthread_exit\fR() +by the terminating thread shall be made available in the location +referenced by +.IR value_ptr . +When a +\fIpthread_join\fR() +returns successfully, the target thread has been terminated. The +results of multiple simultaneous calls to +\fIpthread_join\fR() +specifying the same target thread are undefined. If the thread calling +\fIpthread_join\fR() +is canceled, then the target thread shall not be detached. +.P +It is unspecified whether a thread that has exited but remains unjoined +counts against +{PTHREAD_THREADS_MAX}. +.P +The behavior is undefined if the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +does not refer to a joinable thread. +.P +The behavior is undefined if the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +refers to the calling thread. +.SH "RETURN VALUE" +If successful, the +\fIpthread_join\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_join\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock was detected. +.P +The +\fIpthread_join\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +An example of thread creation and deletion follows: +.sp +.RS 4 +.nf + +typedef struct { + int *ar; + long n; +} subarray; +.P +void * +incer(void *arg) +{ + long i; +.P + for (i = 0; i < ((subarray *)arg)->n; i++) + ((subarray *)arg)->ar[i]++; +} +.P +int main(void) +{ + int ar[1000000]; + pthread_t th1, th2; + subarray sb1, sb2; +.P + sb1.ar = &ar[0]; + sb1.n = 500000; + (void) pthread_create(&th1, NULL, incer, &sb1); +.P + sb2.ar = &ar[500000]; + sb2.n = 500000; + (void) pthread_create(&th2, NULL, incer, &sb2); +.P + (void) pthread_join(th1, NULL); + (void) pthread_join(th2, NULL); + return 0; +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_join\fR() +function is a convenience that has proven useful in multi-threaded +applications. It is true that a programmer could simulate this +function if it were not provided by passing extra state as part of the +argument to the +\fIstart_routine\fR(). +The terminating thread would set a flag to indicate termination and +broadcast a condition that is part of that state; a joining thread +would wait on that condition variable. While such a technique would +allow a thread to wait on more complex conditions (for example, waiting +for multiple threads to terminate), waiting on individual thread +termination is considered widely useful. Also, including the +\fIpthread_join\fR() +function in no way precludes a programmer from coding such complex +waits. Thus, while not a primitive, including +\fIpthread_join\fR() +in this volume of POSIX.1\(hy2017 was considered valuable. +.P +The +\fIpthread_join\fR() +function provides a simple mechanism allowing an application to wait +for a thread to terminate. After the thread terminates, the +application may then choose to clean up resources that were used by the +thread. For instance, after +\fIpthread_join\fR() +returns, any application-provided stack storage could be reclaimed. +.P +The +\fIpthread_join\fR() +or +\fIpthread_detach\fR() +function should eventually be called for every thread that is created +with the +.IR detachstate +attribute set to PTHREAD_CREATE_JOINABLE +so that storage associated with the thread may be reclaimed. +.P +The interaction between +\fIpthread_join\fR() +and cancellation is well-defined for the following reasons: +.IP " *" 4 +The +\fIpthread_join\fR() +function, like all other non-async-cancel-safe functions, can only be +called with +deferred cancelability type. +.IP " *" 4 +Cancellation cannot occur in the disabled cancelability state. +.P +Thus, only the default cancelability state need be considered. As +specified, either the +\fIpthread_join\fR() +call is canceled, or it succeeds, but not both. The difference is +obvious to the application, since either a cancellation handler is run +or +\fIpthread_join\fR() +returns. There are no race conditions since +\fIpthread_join\fR() +was called in the deferred cancelability state. +.P +If an implementation detects that the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +does not refer to a joinable thread, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR thread +argument to +\fIpthread_join\fR() +refers to the calling thread, it is recommended that the function +should fail and report an +.BR [EDEADLK] +error. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_key_create.3p b/upstream/archlinux/man3p/pthread_key_create.3p new file mode 100644 index 00000000..579ceafe --- /dev/null +++ b/upstream/archlinux/man3p/pthread_key_create.3p @@ -0,0 +1,263 @@ +'\" et +.TH PTHREAD_KEY_CREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_key_create +\(em thread-specific data key creation +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_key_create(pthread_key_t *\fIkey\fP, void (*\fIdestructor\fP)(void*)); +.fi +.SH DESCRIPTION +The +\fIpthread_key_create\fR() +function shall create a thread-specific data key visible to all threads +in the process. Key values provided by +\fIpthread_key_create\fR() +are opaque objects used to locate thread-specific data. Although the +same key value may be used by different threads, the values bound to +the key by +\fIpthread_setspecific\fR() +are maintained on a per-thread basis and persist for the life of the +calling thread. +.P +Upon key creation, the value NULL shall be associated with the new key +in all active threads. Upon thread creation, the value NULL shall be +associated with all defined keys in the new thread. +.P +An optional destructor function may be associated with each key value. +At thread exit, if a key value has a non-NULL destructor pointer, and +the thread has a non-NULL value associated with that key, the value of +the key is set to NULL, and then the function pointed to is called with +the previously associated value as its sole argument. The order of +destructor calls is unspecified if more than one destructor exists for +a thread when it exits. +.P +If, after all the destructors have been called for all non-NULL values +with associated destructors, there are still some non-NULL values with +associated destructors, then the process is repeated. If, after at +least +{PTHREAD_DESTRUCTOR_ITERATIONS} +iterations of destructor calls for outstanding non-NULL values, there +are still some non-NULL values with associated destructors, +implementations may stop calling destructors, or they may continue +calling destructors until no non-NULL values with associated +destructors exist, even though this might result in an infinite loop. +.SH "RETURN VALUE" +If successful, the +\fIpthread_key_create\fR() +function shall store the newly created key value at *\fIkey\fP and +shall return zero. Otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_key_create\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources to create another +thread-specific data key, or the system-imposed limit on the total +number of keys per process +{PTHREAD_KEYS_MAX} +has been exceeded. +.TP +.BR ENOMEM +Insufficient memory exists to create the key. +.P +The +\fIpthread_key_create\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The following example demonstrates a function that initializes a +thread-specific data key when it is first called, and associates a +thread-specific object with each calling thread, initializing this +object when necessary. +.sp +.RS 4 +.nf + +static pthread_key_t key; +static pthread_once_t key_once = PTHREAD_ONCE_INIT; +.P +static void +make_key() +{ + (void) pthread_key_create(&key, NULL); +} +.P +func() +{ + void *ptr; +.P + (void) pthread_once(&key_once, make_key); + if ((ptr = pthread_getspecific(key)) == NULL) { + ptr = malloc(OBJECT_SIZE); + ... + (void) pthread_setspecific(key, ptr); + } + ... +} +.fi +.P +.RE +.P +Note that the key has to be initialized before +\fIpthread_getspecific\fR() +or +\fIpthread_setspecific\fR() +can be used. The +\fIpthread_key_create\fR() +call could either be explicitly made in a module initialization +routine, or it can be done implicitly by the first call to a module as +in this example. Any attempt to use the key before it is initialized +is a programming error, making the code below incorrect. +.sp +.RS 4 +.nf + +static pthread_key_t key; +.P +func() +{ + void *ptr; +.P + /* KEY NOT INITIALIZED!!! THIS WILL NOT WORK!!! */ + if ((ptr = pthread_getspecific(key)) == NULL && + pthread_setspecific(key, NULL) != 0) { + pthread_key_create(&key, NULL); + ... + } +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.br +.SH RATIONALE +.SS "Destructor Functions" +.P +Normally, the value bound to a key on behalf of a particular thread is +a pointer to storage allocated dynamically on behalf of the calling +thread. The destructor functions specified with +\fIpthread_key_create\fR() +are intended to be used to free this storage when the thread exits. +Thread +cancellation cleanup handlers cannot be used for this purpose because +thread-specific data may persist outside the lexical scope in which the +cancellation cleanup handlers operate. +.P +If the value associated with a key needs to be updated during the +lifetime of the thread, it may be necessary to release the storage +associated with the old value before the new value is bound. Although +the +\fIpthread_setspecific\fR() +function could do this automatically, this feature is not needed often +enough to justify the added complexity. Instead, the programmer is +responsible for freeing the stale storage: +.sp +.RS 4 +.nf + +pthread_getspecific(key, &old); +new = allocate(); +destructor(old); +pthread_setspecific(key, new); +.fi +.P +.RE +.TP 10 +.BR Note: +The above example could leak storage if run with asynchronous +cancellation enabled. No such problems occur in the default cancellation +state if no cancellation points occur between the get and set. +.P +.P +There is no notion of a destructor-safe function. If an application +does not call +\fIpthread_exit\fR() +from a signal handler, or if it blocks any signal whose handler may +call +\fIpthread_exit\fR() +while calling async-unsafe functions, all functions may be safely +called from destructors. +.SS "Non-Idempotent Data Key Creation" +.P +There were requests to make +\fIpthread_key_create\fR() +idempotent with respect to a given +.IR key +address parameter. This would allow applications to call +\fIpthread_key_create\fR() +multiple times for a given +.IR key +address and be guaranteed that only one key would be created. Doing so +would require the key value to be previously initialized (possibly at +compile time) to a known null value and would require that implicit +mutual-exclusion be performed based on the address and contents of the +.IR key +parameter in order to guarantee that exactly one key would be created. +.P +Unfortunately, the implicit mutual-exclusion would not be limited to +only +\fIpthread_key_create\fR(). +On many implementations, implicit mutual-exclusion would also have to +be performed by +\fIpthread_getspecific\fR() +and +\fIpthread_setspecific\fR() +in order to guard against using incompletely stored or not-yet-visible +key values. This could significantly increase the cost of important +operations, particularly +\fIpthread_getspecific\fR(). +.P +Thus, this proposal was rejected. The +\fIpthread_key_create\fR() +function performs no implicit synchronization. It is the +responsibility of the programmer to ensure that it is called exactly +once per key before use of the key. Several straightforward mechanisms +can already be used to accomplish this, including calling explicit +module initialization functions, using mutexes, and using +\fIpthread_once\fR(). +This places no significant burden on the programmer, introduces no +possibly confusing \fIad hoc\fP implicit synchronization mechanism, and +potentially allows commonly used thread-specific data operations to be +more efficient. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_getspecific\fR\^(\|)", +.IR "\fIpthread_key_delete\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_key_delete.3p b/upstream/archlinux/man3p/pthread_key_delete.3p new file mode 100644 index 00000000..6576f7f6 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_key_delete.3p @@ -0,0 +1,141 @@ +'\" et +.TH PTHREAD_KEY_DELETE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_key_delete +\(em thread-specific data key deletion +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_key_delete(pthread_key_t \fIkey\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_key_delete\fR() +function shall delete a thread-specific data key previously returned by +\fIpthread_key_create\fR(). +The thread-specific data values associated with +.IR key +need not be NULL at the time +\fIpthread_key_delete\fR() +is called. It is the responsibility of the application to free any +application storage or perform any cleanup actions for data structures +related to the deleted key or associated thread-specific data in any +threads; this cleanup can be done either before or after +\fIpthread_key_delete\fR() +is called. Any attempt to use +.IR key +following the call to +\fIpthread_key_delete\fR() +results in undefined behavior. +.P +The +\fIpthread_key_delete\fR() +function shall be callable from within destructor functions. No +destructor functions shall be invoked by +\fIpthread_key_delete\fR(). +Any destructor function that may have been associated with +.IR key +shall no longer be called upon thread exit. +.SH "RETURN VALUE" +If successful, the +\fIpthread_key_delete\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_key_delete\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +A thread-specific data key deletion function has been included in order +to allow the resources associated with an unused thread-specific data +key to be freed. Unused thread-specific data keys can arise, among +other scenarios, when a dynamically loaded module that allocated a key +is unloaded. +.P +Conforming applications are responsible for performing any cleanup +actions needed for data structures associated with the key to be +deleted, including data referenced by thread-specific data values. No +such cleanup is done by +\fIpthread_key_delete\fR(). +In particular, destructor functions are not called. There are several +reasons for this division of responsibility: +.IP " 1." 4 +The associated destructor functions used to free thread-specific data +at thread exit time are only guaranteed to work correctly when called +in the thread that allocated the thread-specific data. (Destructors +themselves may utilize thread-specific data.) Thus, they cannot be used +to free thread-specific data in other threads at key deletion time. +Attempting to have them called by other threads at key deletion time +would require other threads to be asynchronously interrupted. But +since interrupted threads could be in an arbitrary state, including +holding locks necessary for the destructor to run, this approach would +fail. In general, there is no safe mechanism whereby an implementation +could free thread-specific data at key deletion time. +.IP " 2." 4 +Even if there were a means of safely freeing thread-specific data +associated with keys to be deleted, doing so would require that +implementations be able to enumerate the threads with non-NULL data and +potentially keep them from creating more thread-specific data while the +key deletion is occurring. This special case could cause extra +synchronization in the normal case, which would otherwise be +unnecessary. +.P +For an application to know that it is safe to delete a key, it has to +know that all the threads that might potentially ever use the key do +not attempt to use it again. For example, it could know this if all +the client threads have called a cleanup procedure declaring that they +are through with the module that is being shut down, perhaps by setting +a reference count to zero. +.P +If an implementation detects that the value specified by the +.IR key +argument to +\fIpthread_key_delete\fR() +does not refer to a a key value obtained from +\fIpthread_key_create\fR() +or refers to a key that has been deleted with +\fIpthread_key_delete\fR(), +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_key_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_kill.3p b/upstream/archlinux/man3p/pthread_kill.3p new file mode 100644 index 00000000..49f96c8d --- /dev/null +++ b/upstream/archlinux/man3p/pthread_kill.3p @@ -0,0 +1,119 @@ +'\" et +.TH PTHREAD_KILL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_kill +\(em send a signal to a thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_kill(pthread_t \fIthread\fP, int \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_kill\fR() +function shall request that a signal be delivered to the specified +thread. +.P +As in +\fIkill\fR(), +if +.IR sig +is zero, error checking shall be performed but no signal shall +actually be sent. +.SH "RETURN VALUE" +Upon successful completion, the function shall return a value of zero. +Otherwise, the function shall return an error number. If the +\fIpthread_kill\fR() +function fails, no signal shall be sent. +.SH ERRORS +The +\fIpthread_kill\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR sig +argument is an invalid or unsupported signal number. +.P +The +\fIpthread_kill\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_kill\fR() +function provides a mechanism for asynchronously directing a signal at +a thread in the calling process. This could be used, for example, by +one thread to affect broadcast delivery of a signal to a set of +threads. +.P +Note that +\fIpthread_kill\fR() +only causes the signal to be handled in the context of the given +thread; the signal action (termination or stopping) affects the +process as a whole. +.SH RATIONALE +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.P +Existing implementations vary on the result of a +\fIpthread_kill\fR() +with a thread ID indicating an inactive thread (a terminated thread +that has not been detached or joined). Some indicate success on such +a call, while others give an error of +.BR [ESRCH] . +Since the definition of thread lifetime in this volume of POSIX.1\(hy2017 covers inactive +threads, the +.BR [ESRCH] +error as described is inappropriate in this case. In particular, this +means that an application cannot have one thread check for termination +of another with +\fIpthread_kill\fR(). +.SH "FUTURE DIRECTIONS" +A future version of this standard may require that +\fIpthread_kill\fR() +not fail with +.BR [ESRCH] +in the case of sending signals to an inactive thread (a terminated +thread not yet detached or joined), even though no signal will be +delivered because the thread is no longer running. +.SH "SEE ALSO" +.IR "\fIkill\fR\^(\|)", +.IR "\fIpthread_self\fR\^(\|)", +.IR "\fIraise\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_consistent.3p b/upstream/archlinux/man3p/pthread_mutex_consistent.3p new file mode 100644 index 00000000..e9fef036 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_consistent.3p @@ -0,0 +1,122 @@ +'\" et +.TH PTHREAD_MUTEX_CONSISTENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_consistent \(em +mark state protected by robust mutex as consistent +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_consistent(pthread_mutex_t *\fImutex\fP); +.fi +.SH DESCRIPTION +If +.IR mutex +is a robust mutex in an inconsistent state, the +\fIpthread_mutex_consistent\fR() +function can be used to mark the state protected by the mutex +referenced by +.IR mutex +as consistent again. +.P +If an owner of a robust mutex terminates while holding the mutex, the +mutex becomes inconsistent and the next thread that acquires the mutex +lock shall be notified of the state by the return value +.BR [EOWNERDEAD] . +In this case, the mutex does not become normally usable again until the +state is marked consistent. +.P +If the thread which acquired the mutex lock with the return value +.BR [EOWNERDEAD] +terminates before calling either +\fIpthread_mutex_consistent\fR() +or +\fIpthread_mutex_unlock\fR(), +the next thread that acquires the mutex lock shall be notified about +the state of the mutex by the return value +.BR [EOWNERDEAD] . +.P +The behavior is undefined if the value specified by the +.IR mutex +argument to +\fIpthread_mutex_consistent\fR() +does not refer to an initialized mutex. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutex_consistent\fR() +function shall return zero. Otherwise, an error value shall be returned +to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_consistent\fR() +function shall fail if: +.TP +.BR EINVAL +The mutex object referenced by +.IR mutex +is not robust or does not protect an inconsistent state. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIpthread_mutex_consistent\fR() +function is only responsible for notifying the implementation that the +state protected by the mutex has been recovered and that normal +operations with the mutex can be resumed. It is the responsibility of +the application to recover the state so it can be reused. If the +application is not able to perform the recovery, it can notify the +implementation that the situation is unrecoverable by a call to +\fIpthread_mutex_unlock\fR() +without a prior call to +\fIpthread_mutex_consistent\fR(), +in which case subsequent threads that attempt to lock the mutex will +fail to acquire the lock and be returned +.BR [ENOTRECOVERABLE] . +.SH RATIONALE +If an implementation detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_consistent\fR() +does not refer to an initialized mutex, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_destroy.3p b/upstream/archlinux/man3p/pthread_mutex_destroy.3p new file mode 100644 index 00000000..1be3493c --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_destroy.3p @@ -0,0 +1,422 @@ +'\" et +.TH PTHREAD_MUTEX_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_destroy, +pthread_mutex_init +\(em destroy and initialize a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_destroy(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_init(pthread_mutex_t *restrict \fImutex\fP, + const pthread_mutexattr_t *restrict \fIattr\fP); +pthread_mutex_t \fImutex\fP = PTHREAD_MUTEX_INITIALIZER; +.fi +.SH DESCRIPTION +The +\fIpthread_mutex_destroy\fR() +function shall destroy the mutex object referenced by +.IR mutex ; +the mutex object becomes, in effect, uninitialized. An implementation +may cause +\fIpthread_mutex_destroy\fR() +to set the object referenced by +.IR mutex +to an invalid value. +.P +A destroyed mutex object can be reinitialized using +\fIpthread_mutex_init\fR(); +the results of otherwise referencing the object after it has been +destroyed are undefined. +.P +It shall be safe to destroy an initialized mutex that is unlocked. +Attempting to destroy a locked mutex, or a mutex that another thread +is attempting to lock, or a mutex that is being used in a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +call by another thread, results in undefined behavior. +.P +The +\fIpthread_mutex_init\fR() +function shall initialize the mutex referenced by +.IR mutex +with attributes specified by +.IR attr . +If +.IR attr +is NULL, the default mutex attributes are used; the effect shall be the +same as passing the address of a default mutex attributes object. Upon +successful initialization, the state of the mutex becomes initialized +and unlocked. +.P +See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. +.P +Attempting to initialize an already initialized mutex results in +undefined behavior. +.P +In cases where default mutex attributes are appropriate, the macro +PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes. The +effect shall be equivalent to dynamic initialization by a call to +\fIpthread_mutex_init\fR() +with parameter +.IR attr +specified as NULL, except that no error checks are performed. +.P +The behavior is undefined if the value specified by the +.IR mutex +argument to +\fIpthread_mutex_destroy\fR() +does not refer to an initialized mutex. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutex_init\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_destroy\fR() +and +\fIpthread_mutex_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources (other than memory) to +initialize another mutex. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the mutex. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.br +.P +The +\fIpthread_mutex_init\fR() +function may fail if: +.TP +.BR EINVAL +The attributes object referenced by +.IR attr +has the robust mutex attribute set without the process-shared attribute +being set. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_destroy\fR() +does not refer to an initialized mutex, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_destroy\fR() +or +\fIpthread_mutex_init\fR() +refers to a locked mutex or a mutex that is referenced (for example, +while being used in a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR()) +by another thread, or detects that the value specified by the +.IR mutex +argument to +\fIpthread_mutex_init\fR() +refers to an already initialized mutex, it is recommended that the +function should fail and report an +.BR [EBUSY] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutex_init\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SS "Alternate Implementations Possible" +.P +This volume of POSIX.1\(hy2017 supports several alternative implementations of mutexes. +An implementation may store the lock directly in the object of type +.BR pthread_mutex_t . +Alternatively, an implementation may store the lock in the heap and +merely store a pointer, handle, or unique ID in the mutex object. +Either implementation has advantages or may be required on certain +hardware configurations. So that portable code can be written that is +invariant to this choice, this volume of POSIX.1\(hy2017 does not define assignment or +equality for this type, and it uses the term ``initialize'' to +reinforce the (more restrictive) notion that the lock may actually +reside in the mutex object itself. +.P +Note that this precludes an over-specification of the type of the mutex +or condition variable and motivates the opaqueness of the type. +.P +An implementation is permitted, but not required, to have +\fIpthread_mutex_destroy\fR() +store an illegal value into the mutex. This may help detect erroneous +programs that try to lock (or otherwise reference) a mutex that has +already been destroyed. +.SS "Tradeoff Between Error Checks and Performance Supported" +.P +Many error conditions that can occur are not required to be detected by +the implementation in order to let implementations trade off performance +\fIversus\fR degree of error checking according to the needs of their +specific applications and execution environment. As a general rule, +conditions caused by the system (such as insufficient memory) are required +to be detected, but conditions caused by an erroneously coded application +(such as failing to provide adequate synchronization to prevent a mutex +from being deleted while in use) are specified to result in undefined +behavior. +.P +A wide range of implementations is thus made possible. For example, an +implementation intended for application debugging may implement all of +the error checks, but an implementation running a single, provably +correct application under very tight performance constraints in an +embedded computer might implement minimal checks. An implementation +might even be provided in two versions, similar to the options that +compilers provide: a full-checking, but slower version; and a +limited-checking, but faster version. To forbid this optionality would +be a disservice to users. +.P +By carefully limiting the use of ``undefined behavior'' only to things +that an erroneous (badly coded) application might do, and by defining +that resource-not-available errors are mandatory, this volume of POSIX.1\(hy2017 ensures that +a fully-conforming application is portable across the full range of +implementations, while not forcing all implementations to add overhead +to check for numerous things that a correct program never does. When the +behavior is undefined, no error number is specified to be returned on +implementations that do detect the condition. This is because undefined +behavior means \fIanything\fR can happen, which includes returning +with any value (which might happen to be a valid, but different, error +number). However, since the error number might be useful to application +developers when diagnosing problems during application development, a +recommendation is made in rationale that implementors should return a +particular error number if their implementation does detect the condition. +.SS "Why No Limits are Defined" +.P +Defining symbols for the maximum number of mutexes and condition +variables was considered but rejected because the number of these +objects may change dynamically. Furthermore, many implementations +place these objects into application memory; thus, there is no explicit +maximum. +.SS "Static Initializers for Mutexes and Condition Variables" +.P +Providing for static initialization of statically allocated +synchronization objects allows modules with private static +synchronization variables to avoid runtime initialization tests and +overhead. Furthermore, it simplifies the coding of self-initializing +modules. Such modules are common in C libraries, where for various +reasons the design calls for self-initialization instead of requiring +an explicit module initialization function to be called. An example +use of static initialization follows. +.P +Without static initialization, a self-initializing routine +\fIfoo\fR() +might look as follows: +.sp +.RS 4 +.nf + +static pthread_once_t foo_once = PTHREAD_ONCE_INIT; +static pthread_mutex_t foo_mutex; +.P +void foo_init() +{ + pthread_mutex_init(&foo_mutex, NULL); +} +.P +void foo() +{ + pthread_once(&foo_once, foo_init); + pthread_mutex_lock(&foo_mutex); + /* Do work. */ + pthread_mutex_unlock(&foo_mutex); +} +.fi +.P +.RE +.P +With static initialization, the same routine could be coded as +follows: +.sp +.RS 4 +.nf + +static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER; +.P +void foo() +{ + pthread_mutex_lock(&foo_mutex); + /* Do work. */ + pthread_mutex_unlock(&foo_mutex); +} +.fi +.P +.RE +.P +Note that the static initialization both eliminates the need for the +initialization test inside +\fIpthread_once\fR() +and the fetch of &\fIfoo_mutex\fP to learn the address to be passed to +\fIpthread_mutex_lock\fR() +or +\fIpthread_mutex_unlock\fR(). +.P +Thus, the C code written to initialize static objects is simpler on all +systems and is also faster on a large class of systems; those where the +(entire) synchronization object can be stored in application memory. +.P +Yet the locking performance question is likely to be raised for +machines that require mutexes to be allocated out of special memory. +Such machines actually have to have mutexes and possibly condition +variables contain pointers to the actual hardware locks. For static +initialization to work on such machines, +\fIpthread_mutex_lock\fR() +also has to test whether or not the pointer to the actual lock has been +allocated. If it has not, +\fIpthread_mutex_lock\fR() +has to initialize it before use. The reservation of such resources can +be made when the program is loaded, and hence return codes have not +been added to mutex locking and condition variable waiting to indicate +failure to complete initialization. +.P +This runtime test in +\fIpthread_mutex_lock\fR() +would at first seem to be extra work; an extra test is required to see +whether the pointer has been initialized. On most machines this would +actually be implemented as a fetch of the pointer, testing the pointer +against zero, and then using the pointer if it has already been +initialized. While the test might seem to add extra work, the extra +effort of testing a register is usually negligible since no extra +memory references are actually done. As more and more machines provide +caches, the real expenses are memory references, not instructions +executed. +.P +Alternatively, depending on the machine architecture, there are often +ways to eliminate +.IR all +overhead in the most important case: on the lock operations that occur +.IR after +the lock has been initialized. This can be done by shifting more +overhead to the less frequent operation: initialization. Since +out-of-line mutex allocation also means that an address has to be +dereferenced to find the actual lock, one technique that is widely +applicable is to have static initialization store a bogus value for +that address; in particular, an address that causes a machine fault to +occur. When such a fault occurs upon the first attempt to lock such a +mutex, validity checks can be done, and then the correct address for +the actual lock can be filled in. Subsequent lock operations incur no +extra overhead since they do not ``fault''. This is merely one +technique that can be used to support static initialization, while not +adversely affecting the performance of lock acquisition. No doubt +there are other techniques that are highly machine-dependent. +.P +The locking overhead for machines doing out-of-line mutex allocation is +thus similar for modules being implicitly initialized, where it is +improved for those doing mutex allocation entirely inline. The inline +case is thus made much faster, and the out-of-line case is not +significantly worse. +.P +Besides the issue of locking performance for such machines, a concern +is raised that it is possible that threads would serialize contending +for initialization locks when attempting to finish initializing +statically allocated mutexes. (Such finishing would typically involve +taking an internal lock, allocating a structure, storing a pointer to +the structure in the mutex, and releasing the internal lock.) First, +many implementations would reduce such serialization by hashing on the +mutex address. Second, such serialization can only occur a bounded +number of times. In particular, it can happen at most as many times as +there are statically allocated synchronization objects. Dynamically +allocated objects would still be initialized via +\fIpthread_mutex_init\fR() +or +\fIpthread_cond_init\fR(). +.P +Finally, if none of the above optimization techniques for out-of-line +allocation yields sufficient performance for an application on some +implementation, the application can avoid static initialization +altogether by explicitly initializing all synchronization objects with +the corresponding +.IR pthread_*_init (\|) +functions, which are supported by all implementations. An +implementation can also document the tradeoffs and advise which +initialization technique is more efficient for that particular +implementation. +.SS "Destroying Mutexes" +.P +A mutex can be destroyed immediately after it is unlocked. However, +since attempting to destroy a locked mutex, or a mutex that another +thread is attempting to lock, or a mutex that is being used in a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +call by another thread, results in undefined behavior, care must be +taken to ensure that no other thread may be referencing the mutex. +.SS "Robust Mutexes" +.P +Implementations are required to provide robust mutexes +for mutexes with the process-shared attribute set to +PTHREAD_PROCESS_SHARED. Implementations are allowed, but not required, +to provide robust mutexes when the process-shared attribute is set to +PTHREAD_PROCESS_PRIVATE. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_mutex_getprioceiling\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_mutexattr_getpshared\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_getprioceiling.3p b/upstream/archlinux/man3p/pthread_mutex_getprioceiling.3p new file mode 100644 index 00000000..59c77fbf --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_getprioceiling.3p @@ -0,0 +1,153 @@ +'\" et +.TH PTHREAD_MUTEX_GETPRIOCEILING "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_getprioceiling, +pthread_mutex_setprioceiling +\(em get and set the priority ceiling of a mutex +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_getprioceiling(const pthread_mutex_t *restrict \fImutex\fP, + int *restrict \fIprioceiling\fP); +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict \fImutex\fP, + int \fIprioceiling\fP, int *restrict \fIold_ceiling\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutex_getprioceiling\fR() +function shall return the current priority ceiling of the mutex. +.P +The +\fIpthread_mutex_setprioceiling\fR() +function shall attempt to lock the mutex as if by a call to +\fIpthread_mutex_lock\fR(), +except that the process of locking the mutex need not adhere to the +priority protect protocol. On acquiring the mutex it shall change the +mutex's priority ceiling and then release the mutex as if by a call to +\fIpthread_mutex_unlock\fR(). +When the change is successful, the previous value of the priority ceiling +shall be returned in +.IR old_ceiling . +.P +If the +\fIpthread_mutex_setprioceiling\fR() +function fails, the mutex priority ceiling shall not be changed. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_getprioceiling\fR() +and +\fIpthread_mutex_setprioceiling\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The protocol attribute of +.IR mutex +is PTHREAD_PRIO_NONE. +.TP +.BR EPERM +The implementation requires appropriate privileges to perform the +operation and the caller does not have appropriate privileges. +.P +The +\fIpthread_mutex_setprioceiling\fR() +function shall fail if: +.TP +.BR EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for +.IR mutex +has been exceeded. +.TP +.BR EDEADLK +The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current +thread already owns the mutex. +.TP +.BR EINVAL +The mutex was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than +the mutex's current priority ceiling, and the implementation adheres to +the priority protect protocol in the process of locking the mutex. +.TP +.BR ENOTRECOVERABLE +.br +The mutex is a robust mutex and the state protected by the mutex is +not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent (see +.IR "\fIpthread_mutex_lock\fR\^(\|)"). +.P +The +\fIpthread_mutex_setprioceiling\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EINVAL +The priority requested by +.IR prioceiling +is out of range. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state +consistent (see +.IR "\fIpthread_mutex_lock\fR\^(\|)"). +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_init.3p b/upstream/archlinux/man3p/pthread_mutex_init.3p new file mode 100644 index 00000000..ee955fe5 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_init.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_MUTEX_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_init +\(em destroy and initialize a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_init(pthread_mutex_t *restrict \fImutex\fP, + const pthread_mutexattr_t *restrict \fIattr\fP); +pthread_mutex_t \fImutex\fP = PTHREAD_MUTEX_INITIALIZER; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutex_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_lock.3p b/upstream/archlinux/man3p/pthread_mutex_lock.3p new file mode 100644 index 00000000..30544ec7 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_lock.3p @@ -0,0 +1,312 @@ +'\" et +.TH PTHREAD_MUTEX_LOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_lock, +pthread_mutex_trylock, +pthread_mutex_unlock +\(em lock and unlock a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_lock(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_trylock(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_unlock(pthread_mutex_t *\fImutex\fP); +.fi +.SH DESCRIPTION +The mutex object referenced by +.IR mutex +shall be locked by a call to +\fIpthread_mutex_lock\fR() +that returns zero or +.BR [EOWNERDEAD] . +If the mutex is already locked by another thread, the calling thread +shall block until the mutex becomes available. This operation shall +return with the mutex object referenced by +.IR mutex +in the locked state with the calling thread as its owner. If a thread +attempts to relock a mutex that it has already locked, +\fIpthread_mutex_lock\fR() +shall behave as described in the +.BR Relock +column of the following table. If a thread attempts to unlock a mutex +that it has not locked or a mutex which is unlocked, +\fIpthread_mutex_unlock\fR() +shall behave as described in the +.BR "Unlock When Not Owner" +column of the following table. +.TS +center box tab(!); +cB | cB | cB | cB +l | l | l | l. +Mutex Type!Robustness!Relock!Unlock When Not Owner +_ +NORMAL!non-robust!deadlock!undefined behavior +_ +NORMAL!robust!deadlock!error returned +_ +ERRORCHECK!either!error returned!error returned +_ +RECURSIVE!either!recursive!error returned +!!(see below) +_ +DEFAULT!non-robust!undefined!undefined behavior\s-2\(dg\s+2 +!!behavior\s-2\(dg\s+2 +_ +DEFAULT!robust!undefined!error returned +!!behavior\s-2\(dg\s+2 +.TE +.IP "\(dg" 6 +If the mutex type is PTHREAD_MUTEX_DEFAULT, the behavior of +\fIpthread_mutex_lock\fR() +may correspond to one of the three other standard mutex types as described +in the table above. If it does not correspond to one of those three, +the behavior is undefined for the cases marked \(dg. +.P +Where the table indicates recursive behavior, the mutex shall maintain +the concept of a lock count. When a thread successfully acquires a +mutex for the first time, the lock count shall be set to one. Every +time a thread relocks this mutex, the lock count shall be incremented +by one. Each time the thread unlocks the mutex, the lock count shall be +decremented by one. When the lock count reaches zero, the mutex shall +become available for other threads to acquire. +.P +The +\fIpthread_mutex_trylock\fR() +function shall be equivalent to +\fIpthread_mutex_lock\fR(), +except that if the mutex object referenced by +.IR mutex +is currently locked (by any thread, including the current thread), the +call shall return immediately. If the mutex type is +PTHREAD_MUTEX_RECURSIVE and the mutex is currently owned by the +calling thread, the mutex lock count shall be incremented by one and +the +\fIpthread_mutex_trylock\fR() +function shall immediately return success. +.P +The +\fIpthread_mutex_unlock\fR() +function shall release the mutex object referenced by +.IR mutex . +The manner in which a mutex is released is dependent upon the mutex's type +attribute. If there are threads blocked on the mutex object referenced by +.IR mutex +when +\fIpthread_mutex_unlock\fR() +is called, resulting in the mutex becoming available, the scheduling +policy shall determine which thread shall acquire the mutex. +.P +(In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become +available when the count reaches zero and the calling thread no longer +has any locks on this mutex.) +.P +If a signal is delivered to a thread waiting for a mutex, upon return +from the signal handler the thread shall resume waiting for the mutex +as if it was not interrupted. +.P +If +.IR mutex +is a robust mutex and the process containing the owning thread +terminated while holding the mutex lock, a call to +\fIpthread_mutex_lock\fR() +shall return the error value +.BR [EOWNERDEAD] . +If +.IR mutex +is a robust mutex and the owning thread terminated while holding the +mutex lock, a call to +\fIpthread_mutex_lock\fR() +may return the error value +.BR [EOWNERDEAD] +even if the process in which the owning thread resides has not +terminated. In these cases, the mutex is locked by the thread but the +state it protects is marked as inconsistent. The application should +ensure that the state is made consistent for reuse and when that is +complete call +\fIpthread_mutex_consistent\fR(). +If the application is unable to recover the state, it should unlock the +mutex without a prior call to +\fIpthread_mutex_consistent\fR(), +after which the mutex is marked permanently unusable. +.P +If +.IR mutex +does not refer to an initialized mutex object, the behavior of +\fIpthread_mutex_lock\fR(), +\fIpthread_mutex_trylock\fR(), +and +\fIpthread_mutex_unlock\fR() +is undefined. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_lock\fR(), +\fIpthread_mutex_trylock\fR(), +and +\fIpthread_mutex_unlock\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_lock\fR() +and +\fIpthread_mutex_trylock\fR() +functions shall fail if: +.TP +.BR EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for +.IR mutex +has been exceeded. +.TP +.BR EINVAL +The +.IR mutex +was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT +and the calling thread's priority is higher than the mutex's current +priority ceiling. +.TP +.BR ENOTRECOVERABLE +.br +The state protected by the mutex is not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent. +.P +The +\fIpthread_mutex_lock\fR() +function shall fail if: +.TP +.BR EDEADLK +The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current +thread already owns the mutex. +.P +The +\fIpthread_mutex_trylock\fR() +function shall fail if: +.TP +.BR EBUSY +The +.IR mutex +could not be acquired because it was already locked. +.P +The +\fIpthread_mutex_unlock\fR() +function shall fail if: +.TP +.BR EPERM +The mutex type is PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE, +or the mutex is a robust mutex, and the current thread does not own +the mutex. +.br +.P +The +\fIpthread_mutex_lock\fR() +and +\fIpthread_mutex_trylock\fR() +functions may fail if: +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state consistent. +.P +The +\fIpthread_mutex_lock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications that have assumed that non-zero return values are errors +will need updating for use with robust mutexes, since a valid return +for a thread acquiring a mutex which is protecting a currently +inconsistent state is +.BR [EOWNERDEAD] . +Applications that do not check the error returns, due to ruling out the +possibility of such errors arising, should not use robust mutexes. If +an application is supposed to work with normal and robust mutexes it +should check all return values for error conditions and if necessary +take appropriate action. +.SH RATIONALE +Mutex objects are intended to serve as a low-level primitive from which +other thread synchronization functions can be built. As such, the +implementation of mutexes should be as efficient as possible, and this +has ramifications on the features available at the interface. +.P +The mutex functions and the particular default settings of the mutex +attributes have been motivated by the desire to not preclude fast, +inlined implementations of mutex locking and unlocking. +.P +Since most attributes only need to be checked when a thread is going to +be blocked, the use of attributes does not slow the (common) +mutex-locking case. +.P +Likewise, while being able to extract the thread ID of the owner of a +mutex might be desirable, it would require storing the current thread +ID when each mutex is locked, and this could incur unacceptable levels +of overhead. Similar arguments apply to a +.IR mutex_tryunlock +operation. +.P +For further rationale on the extended mutex types, see the Rationale (Informative) volume of POSIX.1\(hy2017, +.IR "Threads Extensions". +.P +If an implementation detects that the value specified by the +.IR mutex +argument does not refer to an initialized mutex object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_mutex_consistent\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_setprioceiling.3p b/upstream/archlinux/man3p/pthread_mutex_setprioceiling.3p new file mode 100644 index 00000000..cc1293ba --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_setprioceiling.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_MUTEX_SETPRIOCEILING "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_setprioceiling +\(em change the priority ceiling of a mutex +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_setprioceiling(pthread_mutex_t *restrict \fImutex\fP, + int \fIprioceiling\fP, int *restrict \fIold_ceiling\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutex_getprioceiling\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_timedlock.3p b/upstream/archlinux/man3p/pthread_mutex_timedlock.3p new file mode 100644 index 00000000..92ea85fb --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_timedlock.3p @@ -0,0 +1,197 @@ +'\" et +.TH PTHREAD_MUTEX_TIMEDLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_timedlock +\(em lock a mutex +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_mutex_timedlock(pthread_mutex_t *restrict \fImutex\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutex_timedlock\fR() +function shall lock the mutex object referenced by +.IR mutex . +If the mutex is already locked, the calling thread shall block +until the mutex becomes available as in the +\fIpthread_mutex_lock\fR() +function. If the mutex cannot be locked without waiting for another +thread to unlock the mutex, this wait shall be terminated when the +specified timeout expires. +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the clock on +which it is based. The +.BR timespec +data type is defined in the +.IR +header. +.P +Under no circumstance shall the function fail with a timeout if the +mutex can be locked immediately. The validity of the +.IR abstime +parameter need not be checked if the mutex can be locked immediately. +.P +As a consequence of the priority inheritance rules (for mutexes +initialized with the PRIO_INHERIT protocol), if a timed mutex wait is +terminated +because its timeout expires, the priority of the owner of the mutex +shall be adjusted as necessary to reflect the fact that this thread is +no longer among the threads waiting for the mutex. +.P +If +.IR mutex +is a robust mutex and the process containing the owning thread +terminated while holding the mutex lock, a call to +\fIpthread_mutex_timedlock\fR() +shall return the error value +.BR [EOWNERDEAD] . +If +.IR mutex +is a robust mutex and the owning thread terminated while holding the +mutex lock, a call to +\fIpthread_mutex_timedlock\fR() +may return the error value +.BR [EOWNERDEAD] +even if the process in which the owning thread resides has not +terminated. In these cases, the mutex is locked by the thread but the +state it protects is marked as inconsistent. The application should +ensure that the state is made consistent for reuse and when that is +complete call +\fIpthread_mutex_consistent\fR(). +If the application is unable to recover the state, it should unlock the +mutex without a prior call to +\fIpthread_mutex_consistent\fR(), +after which the mutex is marked permanently unusable. +.P +If +.IR mutex +does not refer to an initialized mutex object, the behavior is undefined. +.SH "RETURN VALUE" +If successful, the +\fIpthread_mutex_timedlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutex_timedlock\fR() +function shall fail if: +.TP +.BR EAGAIN +The mutex could not be acquired because the maximum number of recursive +locks for +.IR mutex +has been exceeded. +.TP +.BR EDEADLK +The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current +thread already owns the mutex. +.TP +.BR EINVAL +The mutex was created with the protocol attribute having the value +PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than +the mutex' current priority ceiling. +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR ENOTRECOVERABLE +.br +The state protected by the mutex is not recoverable. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the process containing the previous +owning thread terminated while holding the mutex lock. The mutex lock +shall be acquired by the calling thread and it is up to the new owner +to make the state consistent. +.TP +.BR ETIMEDOUT +The mutex could not be locked before the specified timeout expired. +.P +The +\fIpthread_mutex_timedlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EOWNERDEAD +.br +The mutex is a robust mutex and the previous owning thread terminated +while holding the mutex lock. The mutex lock shall be acquired by the +calling thread and it is up to the new owner to make the state consistent. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications that have assumed that non-zero return values are errors +will need updating for use with robust mutexes, since a valid return +for a thread acquiring a mutex which is protecting a currently +inconsistent state is +.BR [EOWNERDEAD] . +Applications that do not check the error returns, due to ruling out the +possibility of such errors arising, should not use robust mutexes. If +an application is supposed to work with normal and robust mutexes, it +should check all return values for error conditions and if necessary +take appropriate action. +.SH RATIONALE +Refer to +.IR "\fIpthread_mutex_lock\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutex_trylock.3p b/upstream/archlinux/man3p/pthread_mutex_trylock.3p new file mode 100644 index 00000000..2b037311 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutex_trylock.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_MUTEX_TRYLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutex_trylock, +pthread_mutex_unlock +\(em lock and unlock a mutex +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutex_trylock(pthread_mutex_t *\fImutex\fP); +int pthread_mutex_unlock(pthread_mutex_t *\fImutex\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutex_lock\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_destroy.3p b/upstream/archlinux/man3p/pthread_mutexattr_destroy.3p new file mode 100644 index 00000000..63177576 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_destroy.3p @@ -0,0 +1,366 @@ +'\" et +.TH PTHREAD_MUTEXATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_destroy, +pthread_mutexattr_init +\(em destroy and initialize the mutex attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_destroy(pthread_mutexattr_t *\fIattr\fP); +int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_destroy\fR() +function shall destroy a mutex attributes object; the object becomes, +in effect, uninitialized. An implementation may cause +\fIpthread_mutexattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_mutexattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. +.P +The +\fIpthread_mutexattr_init\fR() +function shall initialize a mutex attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +Results are undefined if +\fIpthread_mutexattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +After a mutex attributes object has been used to initialize one or more +mutexes, any function affecting the attributes object (including +destruction) shall not affect any previously initialized mutexes. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_destroy\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_mutexattr_destroy\fR() +and +\fIpthread_mutexattr_init\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the mutex attributes object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_destroy\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +See +.IR "\fIpthread_attr_destroy\fR\^(\|)" +for a general explanation of attributes. Attributes objects allow +implementations to experiment with useful extensions and permit +extension of this volume of POSIX.1\(hy2017 without changing the existing functions. Thus, they +provide for future extensibility of this volume of POSIX.1\(hy2017 and reduce the temptation to +standardize prematurely on semantics that are not yet widely +implemented or understood. +.P +Examples of possible additional mutex attributes that have been +discussed are +.IR spin_only , +.IR limited_spin , +.IR no_spin , +.IR recursive , +and +.IR metered . +(To explain what the latter attributes might mean: recursive mutexes +would allow for multiple re-locking by the current owner; metered +mutexes would transparently keep records of queue length, wait time, +and so on.) Since there is not yet wide agreement on the usefulness of +these resulting from shared implementation and usage experience, they +are not yet specified in this volume of POSIX.1\(hy2017. Mutex attributes objects, +however, make it possible to test out these concepts for possible +standardization at a later time. +.SS "Mutex Attributes and Performance" +.P +Care has been taken to ensure that the default values of the mutex +attributes have been defined such that mutexes initialized with the +defaults have simple enough semantics so that the locking and unlocking +can be done with the equivalent of a test-and-set instruction (plus +possibly a few other basic instructions). +.P +There is at least one implementation method that can be used to reduce +the cost of testing at lock-time if a mutex has non-default +attributes. One such method that an implementation can employ (and +this can be made fully transparent to fully conforming POSIX +applications) is to secretly pre-lock any mutexes that are initialized +to non-default attributes. Any later attempt to lock such a mutex +causes the implementation to branch to the ``slow path'' as if the +mutex were unavailable; then, on the slow path, the implementation can +do the ``real work'' to lock a non-default mutex. The underlying +unlock operation is more complicated since the implementation never +really wants to release the pre-lock on this kind of mutex. This +illustrates that, depending on the hardware, there may be certain +optimizations that can be used so that whatever mutex attributes are +considered ``most frequently used'' can be processed most efficiently. +.SS "Process Shared Memory and Synchronization" +.P +The existence of memory mapping functions in this volume of POSIX.1\(hy2017 leads to the +possibility that an application may allocate the synchronization +objects from this section in memory that is accessed by multiple +processes (and therefore, by threads of multiple processes). +.P +In order to permit such usage, while at the same time keeping the usual +case (that is, usage within a single process) efficient, a +.IR process-shared +option has been defined. +.P +If an implementation supports the _POSIX_THREAD_PROCESS_SHARED +option, then the +.IR process-shared +attribute can be used to indicate that mutexes or condition variables +may be accessed by threads of multiple processes. +.P +The default setting of PTHREAD_PROCESS_PRIVATE +has been chosen for the +.IR process-shared +attribute so that the most efficient forms of these synchronization +objects are created by default. +.P +Synchronization variables that are initialized with the +PTHREAD_PROCESS_PRIVATE +.IR process-shared +attribute may only be operated on by threads in the process that +initialized them. Synchronization variables that are initialized with +the PTHREAD_PROCESS_SHARED +.IR process-shared +attribute may be operated on by any thread in any process that has +access to it. In particular, these processes may exist beyond the +lifetime of the initializing process. For example, the following code +implements a simple counting semaphore in a mapped file that may be +used by many processes. +.sp +.RS 4 +.nf + +/* sem.h */ +struct semaphore { + pthread_mutex_t lock; + pthread_cond_t nonzero; + unsigned count; +}; +typedef struct semaphore semaphore_t; +.P +semaphore_t *semaphore_create(char *semaphore_name); +semaphore_t *semaphore_open(char *semaphore_name); +void semaphore_post(semaphore_t *semap); +void semaphore_wait(semaphore_t *semap); +void semaphore_close(semaphore_t *semap); +.P +/* sem.c */ +#include +#include +#include +#include +#include +#include "sem.h" +.P +semaphore_t * +semaphore_create(char *semaphore_name) +{ +int fd; + semaphore_t *semap; + pthread_mutexattr_t psharedm; + pthread_condattr_t psharedc; +.P + fd = open(semaphore_name, O_RDWR | O_CREAT | O_EXCL, 0666); + if (fd < 0) + return (NULL); + (void) ftruncate(fd, sizeof(semaphore_t)); + (void) pthread_mutexattr_init(&psharedm); + (void) pthread_mutexattr_setpshared(&psharedm, + PTHREAD_PROCESS_SHARED); + (void) pthread_condattr_init(&psharedc); + (void) pthread_condattr_setpshared(&psharedc, + PTHREAD_PROCESS_SHARED); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + (void) pthread_mutex_init(&semap->lock, &psharedm); + (void) pthread_cond_init(&semap->nonzero, &psharedc); + semap->count = 0; + return (semap); +} +.P +semaphore_t * +semaphore_open(char *semaphore_name) +{ + int fd; + semaphore_t *semap; +.P + fd = open(semaphore_name, O_RDWR, 0666); + if (fd < 0) + return (NULL); + semap = (semaphore_t *) mmap(NULL, sizeof(semaphore_t), + PROT_READ | PROT_WRITE, MAP_SHARED, + fd, 0); + close (fd); + return (semap); +} +.P +void +semaphore_post(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + if (semap->count == 0) + pthread_cond_signal(&semapx->nonzero); + semap->count++; + pthread_mutex_unlock(&semap->lock); +} +.P +void +semaphore_wait(semaphore_t *semap) +{ + pthread_mutex_lock(&semap->lock); + while (semap->count == 0) + pthread_cond_wait(&semap->nonzero, &semap->lock); + semap->count--; + pthread_mutex_unlock(&semap->lock); +} +.P +void +semaphore_close(semaphore_t *semap) +{ + munmap((void *) semap, sizeof(semaphore_t)); +} +.fi +.P +.RE +.P +The following code is for three separate processes that create, post, +and wait on a semaphore in the file +.BR /tmp/semaphore . +Once the file is created, the post and wait programs increment and +decrement the counting semaphore (waiting and waking as required) even +though they did not initialize the semaphore. +.sp +.RS 4 +.nf + +/* create.c */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_create("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_close(semap); + return (0); +} +.P +/* post */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_post(semap); + semaphore_close(semap); + return (0); +} +.P +/* wait */ +#include "pthread.h" +#include "sem.h" +.P +int +main() +{ + semaphore_t *semap; +.P + semap = semaphore_open("/tmp/semaphore"); + if (semap == NULL) + exit(1); + semaphore_wait(semap); + semaphore_close(semap); + return (0); +} +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_getprioceiling.3p b/upstream/archlinux/man3p/pthread_mutexattr_getprioceiling.3p new file mode 100644 index 00000000..d063ca5c --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_getprioceiling.3p @@ -0,0 +1,125 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPRIOCEILING "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_getprioceiling, +pthread_mutexattr_setprioceiling +\(em get and set the prioceiling attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t + *restrict \fIattr\fP, int *restrict \fIprioceiling\fP); +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *\fIattr\fP, + int \fIprioceiling\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getprioceiling\fR() +and +\fIpthread_mutexattr_setprioceiling\fR() +functions, respectively, shall get and set the priority ceiling +attribute of a mutex attributes object pointed to by +.IR attr +which was previously created by the function +\fIpthread_mutexattr_init\fR(). +.P +The +.IR prioceiling +attribute contains the priority ceiling of initialized mutexes. The +values of +.IR prioceiling +are within the maximum range of priorities defined by SCHED_FIFO. +.P +The +.IR prioceiling +attribute defines the priority ceiling of initialized mutexes, which is +the minimum priority level at which the critical section guarded by the +mutex is executed. In order to avoid priority inversion, the priority +ceiling of the mutex shall be set to a priority higher than or equal to +the highest priority of all the threads that may lock that mutex. The +values of +.IR prioceiling +are within the maximum range of priorities defined under the SCHED_FIFO +scheduling policy. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprioceiling\fR() +or +\fIpthread_mutexattr_setprioceiling\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_getprioceiling\fR() +and +\fIpthread_mutexattr_setprioceiling\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR prioceiling +is invalid. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprioceiling\fR() +or +\fIpthread_mutexattr_setprioceiling\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_getprotocol.3p b/upstream/archlinux/man3p/pthread_mutexattr_getprotocol.3p new file mode 100644 index 00000000..978e32e2 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_getprotocol.3p @@ -0,0 +1,199 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPROTOCOL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_getprotocol, +pthread_mutexattr_setprotocol +\(em get and set the protocol attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getprotocol(const pthread_mutexattr_t + *restrict \fIattr\fP, int *restrict \fIprotocol\fP); +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *\fIattr\fP, + int \fIprotocol\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getprotocol\fR() +and +\fIpthread_mutexattr_setprotocol\fR() +functions, respectively, shall get and set the protocol attribute of +a mutex attributes object pointed to by +.IR attr +which was previously created by the function +\fIpthread_mutexattr_init\fR(). +.P +The +.IR protocol +attribute defines the protocol to be followed in utilizing mutexes. +The value of +.IR protocol +may be one of: +.P +.nf +PTHREAD_PRIO_INHERIT +PTHREAD_PRIO_NONE +PTHREAD_PRIO_PROTECT +.fi +.P +which are defined in the +.IR +header. The default value of the attribute shall be PTHREAD_PRIO_NONE. +.P +When a thread owns a mutex with the PTHREAD_PRIO_NONE +.IR protocol +attribute, its priority and scheduling shall not be affected by +its mutex ownership. +.P +When a thread is blocking higher priority threads because of owning one +or more robust mutexes with the PTHREAD_PRIO_INHERIT +.IR protocol +attribute, it shall execute at the higher of its priority or the priority +of the highest priority thread waiting on any of the robust mutexes +owned by this thread and initialized with this protocol. +.P +When a thread is blocking higher priority threads because of owning one +or more non-robust mutexes with the PTHREAD_PRIO_INHERIT +.IR protocol +attribute, it shall execute at the higher of its priority or the priority +of the highest priority thread waiting on any of the non-robust mutexes +owned by this thread and initialized with this protocol. +.P +When a thread owns one or more robust mutexes initialized with the +PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its +priority or the highest of the priority ceilings of all the robust mutexes +owned by this thread and initialized with this attribute, regardless of +whether other threads are blocked on any of these robust mutexes or not. +.P +When a thread owns one or more non-robust mutexes initialized with the +PTHREAD_PRIO_PROTECT protocol, it shall execute at the higher of its +priority or the highest of the priority ceilings of all the non-robust +mutexes owned by this thread and initialized with this attribute, +regardless of whether other threads are blocked on any of these non-robust +mutexes or not. +.P +While a thread is holding a mutex which has been initialized with the +PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it +shall not be subject to being moved to the tail of the scheduling queue +at its priority in the event that its original priority is changed, +such as by a call to +\fIsched_setparam\fR(). +Likewise, when a thread unlocks a mutex that has been initialized with +the PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, +it shall not be subject to being moved to the tail of the scheduling +queue at its priority in the event that its original priority is +changed. +.P +If a thread simultaneously owns several mutexes initialized with +different protocols, it shall execute at the highest of the priorities +that it would have obtained by each of these protocols. +.P +When a thread makes a call to +\fIpthread_mutex_lock\fR(), +the mutex was initialized with the protocol attribute having the value +PTHREAD_PRIO_INHERIT, when the calling thread is blocked because the +mutex is owned by another thread, that owner thread shall inherit the +priority level of the calling thread as long as it continues to own the +mutex. The implementation shall update its execution priority to the +maximum of its assigned priority and all its inherited priorities. +Furthermore, if this owner thread itself becomes blocked on another +mutex with the +.IR protocol +attribute having the value PTHREAD_PRIO_INHERIT, the same priority +inheritance effect shall be propagated to this other owner thread, +in a recursive manner. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprotocol\fR() +or +\fIpthread_mutexattr_setprotocol\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_getprotocol\fR() +and +\fIpthread_mutexattr_setprotocol\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_setprotocol\fR() +function shall fail if: +.TP +.BR ENOTSUP +The value specified by +.IR protocol +is an unsupported value. +.P +The +\fIpthread_mutexattr_getprotocol\fR() +and +\fIpthread_mutexattr_setprotocol\fR() +functions may fail if: +.TP +.BR EINVAL +The value specified by +.IR protocol +is invalid. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getprotocol\fR() +or +\fIpthread_mutexattr_setprotocol\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_getpshared.3p b/upstream/archlinux/man3p/pthread_mutexattr_getpshared.3p new file mode 100644 index 00000000..1720acf6 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_getpshared.3p @@ -0,0 +1,129 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_getpshared, +pthread_mutexattr_setpshared +\(em get and set the process-shared attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getpshared(const pthread_mutexattr_t + *restrict \fIattr\fP, int *restrict \fIpshared\fP); +int pthread_mutexattr_setpshared(pthread_mutexattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the attributes object referenced by +.IR attr . +.P +The +\fIpthread_mutexattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex +to be operated upon by any thread that has access to the memory where +the mutex is allocated, even if the mutex is allocated in memory that +is shared by multiple processes. See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. The default value of the attribute +shall be PTHREAD_PROCESS_PRIVATE. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getpshared\fR() +or +\fIpthread_mutexattr_setpshared\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_mutexattr_setpshared\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.P +Upon successful completion, +\fIpthread_mutexattr_getpshared\fR() +shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_mutexattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the attribute is outside the range of legal +values for that attribute. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getpshared\fR() +or +\fIpthread_mutexattr_setpshared\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_cond_destroy\fR\^(\|)", +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutexattr_destroy\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_getrobust.3p b/upstream/archlinux/man3p/pthread_mutexattr_getrobust.3p new file mode 100644 index 00000000..9b134ffc --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_getrobust.3p @@ -0,0 +1,164 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETROBUST "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_getrobust, +pthread_mutexattr_setrobust +\(em get and set the mutex robust attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_getrobust(const pthread_mutexattr_t *restrict + \fIattr\fP, int *restrict \fIrobust\fP); +int pthread_mutexattr_setrobust(pthread_mutexattr_t *\fIattr\fP, + int \fIrobust\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_getrobust\fR() +and +\fIpthread_mutexattr_setrobust\fR() +functions, respectively, shall get and set the mutex +.IR robust +attribute. This attribute is set in the +.IR robust +parameter. Valid values for +.IR robust +include: +.IP PTHREAD_MUTEX_STALLED 6 +.br +No special actions are taken if the owner of the mutex is terminated +while holding the mutex lock. This can lead to deadlocks if no other +thread can unlock the mutex. +.br +This is the default value. +.IP PTHREAD_MUTEX_ROBUST 6 +.br +If the process containing the owning thread of a robust mutex +terminates while holding the mutex lock, the next thread that acquires +the mutex shall be notified about the termination by the return value +.BR [EOWNERDEAD] +from the locking function. If the owning thread of a robust mutex +terminates while holding the mutex lock, the next thread that attempts +to acquire the mutex may be notified about the termination by the +return value +.BR [EOWNERDEAD] . +The notified thread can then attempt to make the state protected +by the mutex consistent again, and if successful can mark the +mutex state as consistent by calling +\fIpthread_mutex_consistent\fR(). +After a subsequent successful call to +\fIpthread_mutex_unlock\fR(), +the mutex lock shall be released and can be used normally by other +threads. If the mutex is unlocked without a call to +\fIpthread_mutex_consistent\fR(), +it shall be in a permanently unusable state and all attempts to lock +the mutex shall fail with the error +.BR [ENOTRECOVERABLE] . +The only permissible operation on such a mutex is +\fIpthread_mutex_destroy\fR(). +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getrobust\fR() +or +\fIpthread_mutexattr_setrobust\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_getrobust\fR() +function shall return zero and store the value of the +.IR robust +attribute of +.IR attr +into the object referenced by the +.IR robust +parameter. Otherwise, an error value shall be returned to indicate the +error. If successful, the +\fIpthread_mutexattr_setrobust\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_setrobust\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR robust +is invalid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The actions required to make the state protected by the mutex +consistent again are solely dependent on the application. If it is not +possible to make the state of a mutex consistent, robust mutexes can be +used to notify this situation by calling +\fIpthread_mutex_unlock\fR() +without a prior call to +\fIpthread_mutex_consistent\fR(). +.P +If the state is declared inconsistent by calling +\fIpthread_mutex_unlock\fR() +without a prior call to +\fIpthread_mutex_consistent\fR(), +a possible approach could be to destroy the mutex and then reinitialize +it. However, it should be noted that this is possible only in certain +situations where the state protected by the mutex has to be +reinitialized and coordination achieved with other threads blocked on +the mutex, because otherwise a call to a locking function with a +reference to a mutex object invalidated by a call to +\fIpthread_mutex_destroy\fR() +results in undefined behavior. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_getrobust\fR() +or +\fIpthread_mutexattr_setrobust\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_mutex_consistent\fR\^(\|)", +.IR "\fIpthread_mutex_destroy\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_gettype.3p b/upstream/archlinux/man3p/pthread_mutexattr_gettype.3p new file mode 100644 index 00000000..d86cece4 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_gettype.3p @@ -0,0 +1,137 @@ +'\" et +.TH PTHREAD_MUTEXATTR_GETTYPE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_gettype, +pthread_mutexattr_settype +\(em get and set the mutex type attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_gettype(const pthread_mutexattr_t *restrict \fIattr\fP, + int *restrict \fItype\fP); +int pthread_mutexattr_settype(pthread_mutexattr_t *\fIattr\fP, int \fItype\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_mutexattr_gettype\fR() +and +\fIpthread_mutexattr_settype\fR() +functions, respectively, shall get and set the mutex +.IR type +attribute. This attribute is set in the +.IR type +parameter to these functions. The default value of the +.IR type +attribute is PTHREAD_MUTEX_DEFAULT. +.P +The type of mutex is contained in the +.IR type +attribute of the mutex attributes. Valid mutex types include: +.sp +.RS +PTHREAD_MUTEX_NORMAL +PTHREAD_MUTEX_ERRORCHECK +PTHREAD_MUTEX_RECURSIVE +PTHREAD_MUTEX_DEFAULT +.RE +.P +The mutex type affects the behavior of calls which lock and unlock the +mutex. See +.IR "\fIpthread_mutex_lock\fR\^(\|)" +for details. An implementation may map PTHREAD_MUTEX_DEFAULT to one of +the other mutex types. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_gettype\fR() +or +\fIpthread_mutexattr_settype\fR() +does not refer to an initialized mutex attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_mutexattr_gettype\fR() +function shall return zero and store the value of the +.IR type +attribute of +.IR attr +into the object referenced by the +.IR type +parameter. Otherwise, an error shall be returned to indicate the error. +.P +If successful, the +\fIpthread_mutexattr_settype\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_mutexattr_settype\fR() +function shall fail if: +.TP +.BR EINVAL +The value +.IR type +is invalid. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +It is advised that an application should not use a +PTHREAD_MUTEX_RECURSIVE mutex with condition variables +because the implicit unlock performed for a +\fIpthread_cond_timedwait\fR() +or +\fIpthread_cond_wait\fR() +may not actually release the mutex (if it had been locked multiple +times). If this happens, no other thread can satisfy the condition of +the predicate. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_mutexattr_gettype\fR() +or +\fIpthread_mutexattr_settype\fR() +does not refer to an initialized mutex attributes object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_cond_timedwait\fR\^(\|)", +.IR "\fIpthread_mutex_lock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_init.3p b/upstream/archlinux/man3p/pthread_mutexattr_init.3p new file mode 100644 index 00000000..5ebcb086 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_init.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEXATTR_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_init +\(em initialize the mutex attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_init(pthread_mutexattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_setprioceiling.3p b/upstream/archlinux/man3p/pthread_mutexattr_setprioceiling.3p new file mode 100644 index 00000000..722c5e3c --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_setprioceiling.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPRIOCEILING "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_setprioceiling +\(em set the prioceiling attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *\fIattr\fP, + int \fIprioceiling\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getprioceiling\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_setprotocol.3p b/upstream/archlinux/man3p/pthread_mutexattr_setprotocol.3p new file mode 100644 index 00000000..fad6187d --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_setprotocol.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPROTOCOL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_setprotocol +\(em set the protocol attribute of the mutex attributes object +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setprotocol(pthread_mutexattr_t *\fIattr\fP, + int \fIprotocol\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getprotocol\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_setpshared.3p b/upstream/archlinux/man3p/pthread_mutexattr_setpshared.3p new file mode 100644 index 00000000..f183d455 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_setpshared.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_setpshared +\(em set the process-shared attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setpshared(pthread_mutexattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getpshared\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_setrobust.3p b/upstream/archlinux/man3p/pthread_mutexattr_setrobust.3p new file mode 100644 index 00000000..e64ad5ee --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_setrobust.3p @@ -0,0 +1,41 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETROBUST "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_setrobust +\(em get and set the mutex robust attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_setrobust(pthread_mutexattr_t *\fIattr\fP, + int \fIrobust\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_getrobust\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_mutexattr_settype.3p b/upstream/archlinux/man3p/pthread_mutexattr_settype.3p new file mode 100644 index 00000000..27ffe1fb --- /dev/null +++ b/upstream/archlinux/man3p/pthread_mutexattr_settype.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_MUTEXATTR_SETTYPE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_mutexattr_settype +\(em set the mutex type attribute +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_mutexattr_settype(pthread_mutexattr_t *\fIattr\fP, int \fItype\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_mutexattr_gettype\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_once.3p b/upstream/archlinux/man3p/pthread_once.3p new file mode 100644 index 00000000..c9007ef8 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_once.3p @@ -0,0 +1,197 @@ +'\" et +.TH PTHREAD_ONCE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_once +\(em dynamic package initialization +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_once(pthread_once_t *\fIonce_control\fP, + void (*\fIinit_routine\fP)(void)); +pthread_once_t \fIonce_control\fP = PTHREAD_ONCE_INIT; +.fi +.SH DESCRIPTION +The first call to +\fIpthread_once\fR() +by any thread in a process, with a given +.IR once_control , +shall call the +.IR init_routine +with no arguments. Subsequent calls of +\fIpthread_once\fR() +with the same +.IR once_control +shall not call the +.IR init_routine . +On return from +\fIpthread_once\fR(), +.IR init_routine +shall have completed. The +.IR once_control +parameter shall determine whether the associated initialization +routine has been called. +.P +The +\fIpthread_once\fR() +function is not a cancellation point. However, if +.IR init_routine +is a cancellation point and is canceled, the effect on +.IR once_control +shall be as if +\fIpthread_once\fR() +was never called. +.P +If the call to +.IR init_routine +is terminated by a call to +\fIlongjmp\fR(), +\fI_longjmp\fR(), +or +\fIsiglongjmp\fR(), +the behavior is undefined. +.P +The constant PTHREAD_ONCE_INIT is defined in the +.IR +header. +.P +The behavior of +\fIpthread_once\fR() +is undefined if +.IR once_control +has automatic storage duration or is not initialized by +PTHREAD_ONCE_INIT. +.SH "RETURN VALUE" +Upon successful completion, +\fIpthread_once\fR() +shall return zero; otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIpthread_once\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If +.IR init_routine +recursively calls +\fIpthread_once\fR() +with the same +.IR once_control , +the recursive call will not call the specified +.IR init_routine , +and thus the specified +.IR init_routine +will not complete, and thus the recursive call to +\fIpthread_once\fR() +will not return. Use of +\fIlongjmp\fR(), +\fI_longjmp\fR(), +or +\fIsiglongjmp\fR() +within an +.IR init_routine +to jump to a point outside of +.IR init_routine +prevents +.IR init_routine +from returning. +.SH RATIONALE +Some C libraries are designed for dynamic initialization. That is, the +global initialization for the library is performed when the first +procedure in the library is called. In a single-threaded program, this +is normally implemented using a static variable whose value is checked +on entry to a routine, as follows: +.sp +.RS 4 +.nf + +static int random_is_initialized = 0; +extern void initialize_random(void); +.P +int random_function() +{ + if (random_is_initialized == 0) { + initialize_random(); + random_is_initialized = 1; + } + ... /* Operations performed after initialization. */ +} +.fi +.P +.RE +.P +To keep the same structure in a multi-threaded program, a new primitive +is needed. Otherwise, library initialization has to be accomplished by +an explicit call to a library-exported initialization function prior to +any use of the library. +.P +For dynamic library initialization in a multi-threaded process, if an +initialization flag is used the flag needs to be protected against +modification by multiple threads simultaneously calling into the +library. This can be done by using a mutex (initialized by assigning +PTHREAD_MUTEX_INITIALIZER). However, the better solution is to use +\fIpthread_once\fR() +which is designed for exactly this purpose, as follows: +.sp +.RS 4 +.nf + +#include +static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT; +extern void initialize_random(void); +.P +int random_function() +{ + (void) pthread_once(&random_is_initialized, initialize_random); + ... /* Operations performed after initialization. */ +} +.fi +.P +.RE +.P +If an implementation detects that the value specified by the +.IR once_control +argument to +\fIpthread_once\fR() +does not refer to a +.BR pthread_once_t +object initialized by PTHREAD_ONCE_INIT, it is recommended that the +function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_destroy.3p b/upstream/archlinux/man3p/pthread_rwlock_destroy.3p new file mode 100644 index 00000000..e05013ba --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_destroy.3p @@ -0,0 +1,186 @@ +'\" et +.TH PTHREAD_RWLOCK_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_destroy, +pthread_rwlock_init +\(em destroy and initialize a read-write lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_destroy(pthread_rwlock_t *\fIrwlock\fP); +int pthread_rwlock_init(pthread_rwlock_t *restrict \fIrwlock\fP, + const pthread_rwlockattr_t *restrict \fIattr\fP); +pthread_rwlock_t \fIrwlock\fR = PTHREAD_RWLOCK_INITIALIZER; +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_destroy\fR() +function shall destroy the read-write lock object referenced by +.IR rwlock +and release any resources used by the lock. The effect of subsequent +use of the lock is undefined until the lock is reinitialized by +another call to +\fIpthread_rwlock_init\fR(). +An implementation may cause +\fIpthread_rwlock_destroy\fR() +to set the object referenced by +.IR rwlock +to an invalid value. Results are undefined if +\fIpthread_rwlock_destroy\fR() +is called when any thread holds +.IR rwlock . +Attempting to destroy an uninitialized read-write lock results in +undefined behavior. +.P +The +\fIpthread_rwlock_init\fR() +function shall allocate any resources required to use the read-write +lock referenced by +.IR rwlock +and initializes the lock to an unlocked state with attributes +referenced by +.IR attr . +If +.IR attr +is NULL, the default read-write lock attributes shall be used; the +effect is the same as passing the address of a default read-write lock +attributes object. Once initialized, the lock can be used any number of +times without being reinitialized. Results are undefined if +\fIpthread_rwlock_init\fR() +is called specifying an already initialized read-write lock. Results +are undefined if a read-write lock is used without first being +initialized. +.P +If the +\fIpthread_rwlock_init\fR() +function fails, +.IR rwlock +shall not be initialized and the contents of +.IR rwlock +are undefined. +.P +See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. +.P +In cases where default read-write lock attributes are appropriate, the +macro PTHREAD_RWLOCK_INITIALIZER can be used to initialize read-write +locks. The effect shall be equivalent to dynamic initialization by a +call to +\fIpthread_rwlock_init\fR() +with the +.IR attr +parameter specified as NULL, except that no error checks are performed. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_rwlock_init\fR() +does not refer to an initialized read-write lock attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlock_destroy\fR() +and +\fIpthread_rwlock_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlock_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacked the necessary resources (other than memory) to +initialize another read-write lock. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the read-write lock. +.TP +.BR EPERM +The caller does not have the privilege to perform the operation. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these and related read-write lock functions may be +subject to priority inversion, as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_destroy\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_rwlock_init\fR() +does not refer to an initialized read-write lock attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_destroy\fR() +or +\fIpthread_rwlock_init\fR() +refers to a locked read-write lock object, or detects that the value +specified by the +.IR rwlock +argument to +\fIpthread_rwlock_init\fR() +refers to an already initialized read-write lock object, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_rdlock.3p b/upstream/archlinux/man3p/pthread_rwlock_rdlock.3p new file mode 100644 index 00000000..100bbab0 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_rdlock.3p @@ -0,0 +1,184 @@ +'\" et +.TH PTHREAD_RWLOCK_RDLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_rdlock, +pthread_rwlock_tryrdlock +\(em lock a read-write lock object for reading +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_rdlock(pthread_rwlock_t *\fIrwlock\fP); +int pthread_rwlock_tryrdlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_rdlock\fR() +function shall apply a read lock to the read-write lock referenced by +.IR rwlock . +The calling thread acquires the read lock if a writer does not hold the +lock and there are no writers blocked on the lock. +.P +If the Thread Execution Scheduling option is supported, and the threads +involved in the lock are executing with the scheduling policies +SCHED_FIFO or SCHED_RR, the calling thread shall +not acquire the lock if a writer holds the lock or if writers of higher +or equal priority are blocked on the lock; otherwise, the calling +thread shall acquire the lock. +.P +If the Thread Execution Scheduling option is supported, and the +threads involved in the lock are executing with the SCHED_SPORADIC +scheduling policy, the calling thread shall not acquire the lock if a +writer holds the lock or if writers of higher or equal priority are +blocked on the lock; otherwise, the calling thread shall acquire the +lock. +.P +If the Thread Execution Scheduling option is not supported, it is +implementation-defined whether the calling thread acquires the lock +when a writer does not hold the lock and there are writers blocked on +the lock. If a writer holds the lock, the calling thread shall not +acquire the read lock. If the read lock is not acquired, the calling +thread shall block until it can acquire the lock. The calling thread +may deadlock if at the time the call is made it holds a write lock. +.P +A thread may hold multiple concurrent read locks on +.IR rwlock +(that is, successfully call the +\fIpthread_rwlock_rdlock\fR() +function +.IR n +times). If so, the application shall ensure that the thread performs +matching unlocks (that is, it calls the +\fIpthread_rwlock_unlock\fR() +function +.IR n +times). +.P +The maximum number of simultaneous read locks that an implementation +guarantees can be applied to a read-write lock shall be +implementation-defined. The +\fIpthread_rwlock_rdlock\fR() +function may fail if this maximum would be exceeded. +.P +The +\fIpthread_rwlock_tryrdlock\fR() +function shall apply a read lock as in the +\fIpthread_rwlock_rdlock\fR() +function, with the exception that the function shall fail if the +equivalent +\fIpthread_rwlock_rdlock\fR() +call would have blocked the calling thread. In no case shall the +\fIpthread_rwlock_tryrdlock\fR() +function ever block; it always either acquires the lock or fails and +returns immediately. +.P +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.P +If a signal is delivered to a thread waiting for a read-write lock for +reading, upon return from the signal handler the thread resumes waiting +for the read-write lock for reading as if it was not interrupted. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlock_rdlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.P +The +\fIpthread_rwlock_tryrdlock\fR() +function shall return zero if the lock for reading on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_rwlock_tryrdlock\fR() +function shall fail if: +.TP +.BR EBUSY +The read-write lock could not be acquired for reading because a writer +holds the lock or a writer with the appropriate priority was blocked on it. +.P +The +\fIpthread_rwlock_rdlock\fR() +and +\fIpthread_rwlock_tryrdlock\fR() +functions may fail if: +.TP +.BR EAGAIN +The read lock could not be acquired because the maximum number of read +locks for +.IR rwlock +has been exceeded. +.P +The +\fIpthread_rwlock_rdlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected or the current thread already owns +the read-write lock for writing. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_rdlock\fR() +or +\fIpthread_rwlock_tryrdlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_timedrdlock.3p b/upstream/archlinux/man3p/pthread_rwlock_timedrdlock.3p new file mode 100644 index 00000000..3d224315 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_timedrdlock.3p @@ -0,0 +1,150 @@ +'\" et +.TH PTHREAD_RWLOCK_TIMEDRDLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_timedrdlock +\(em lock a read-write lock for reading +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict \fIrwlock\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_timedrdlock\fR() +function shall apply a read lock to the read-write lock referenced by +.IR rwlock +as in the +\fIpthread_rwlock_rdlock\fR() +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the +CLOCK_REALTIME clock. The +.BR timespec +data type is defined in the +.IR +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +.IR abstime +parameter need not be checked if the lock can be immediately acquired. +.P +If a signal that causes a signal handler to be executed is delivered to +a thread blocked on a read-write lock via a call to +\fIpthread_rwlock_timedrdlock\fR(), +upon return from the signal handler the thread shall resume waiting for +the lock as if it was not interrupted. +.P +The calling thread may deadlock if at the time the call is made it +holds a write lock on +.IR rwlock . +The results are undefined if this function is called with an +uninitialized read-write lock. +.SH "RETURN VALUE" +The +\fIpthread_rwlock_timedrdlock\fR() +function shall return zero if the lock for reading on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_rwlock_timedrdlock\fR() +function shall fail if: +.TP +.BR ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.P +The +\fIpthread_rwlock_timedrdlock\fR() +function may fail if: +.TP +.BR EAGAIN +The read lock could not be acquired because the maximum number of read +locks for lock would be exceeded. +.TP +.BR EDEADLK +A deadlock condition was detected or the calling thread already holds a +write lock on +.IR rwlock . +.TP +.BR EINVAL +The +.IR abstime +nanosecond value is less than zero or greater than or equal to 1\|000 +million. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_timedrdlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_timedwrlock.3p b/upstream/archlinux/man3p/pthread_rwlock_timedwrlock.3p new file mode 100644 index 00000000..e2daaf91 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_timedwrlock.3p @@ -0,0 +1,143 @@ +'\" et +.TH PTHREAD_RWLOCK_TIMEDWRLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_timedwrlock +\(em lock a read-write lock for writing +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict \fIrwlock\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_timedwrlock\fR() +function shall apply a write lock to the read-write lock referenced by +.IR rwlock +as in the +\fIpthread_rwlock_wrlock\fR() +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the +CLOCK_REALTIME clock. The +.BR timespec +data type is defined in the +.IR +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +.IR abstime +parameter need not be checked if the lock can be immediately acquired. +.P +If a signal that causes a signal handler to be executed is delivered to +a thread blocked on a read-write lock via a call to +\fIpthread_rwlock_timedwrlock\fR(), +upon return from the signal handler the thread shall resume waiting for +the lock as if it was not interrupted. +.P +The calling thread may deadlock if at the time the call is made it +holds the read-write lock. The results are undefined if this function +is called with an uninitialized read-write lock. +.SH "RETURN VALUE" +The +\fIpthread_rwlock_timedwrlock\fR() +function shall return zero if the lock for writing on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.SH ERRORS +The +\fIpthread_rwlock_timedwrlock\fR() +function shall fail if: +.TP +.BR ETIMEDOUT +The lock could not be acquired before the specified timeout expired. +.P +The +\fIpthread_rwlock_timedwrlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected or the calling thread already holds the +.IR rwlock . +.TP +.BR EINVAL +The +.IR abstime +nanosecond value is less than zero or greater than or equal to 1\|000 +million. +.P +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_timedwrlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_tryrdlock.3p b/upstream/archlinux/man3p/pthread_rwlock_tryrdlock.3p new file mode 100644 index 00000000..40da34b3 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_tryrdlock.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_RWLOCK_TRYRDLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_tryrdlock +\(em lock a read-write lock object for reading +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_tryrdlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_trywrlock.3p b/upstream/archlinux/man3p/pthread_rwlock_trywrlock.3p new file mode 100644 index 00000000..be9c5078 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_trywrlock.3p @@ -0,0 +1,136 @@ +'\" et +.TH PTHREAD_RWLOCK_TRYWRLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_trywrlock, +pthread_rwlock_wrlock +\(em lock a read-write lock object for writing +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_trywrlock(pthread_rwlock_t *\fIrwlock\fP); +int pthread_rwlock_wrlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_trywrlock\fR() +function shall apply a write lock like the +\fIpthread_rwlock_wrlock\fR() +function, with the exception that the function shall fail if any thread +currently holds +.IR rwlock +(for reading or writing). +.P +The +\fIpthread_rwlock_wrlock\fR() +function shall apply a write lock to the read-write lock referenced by +.IR rwlock . +The calling thread shall acquire the write lock if no thread (reader +or writer) holds the read-write lock +.IR rwlock . +Otherwise, if another thread holds the read-write lock +.IR rwlock , +the calling thread shall block until it can acquire the lock. +If a deadlock condition occurs or the calling thread already owns the +read-write lock for writing or reading, the call shall either deadlock +or return +.BR [EDEADLK] . +.P +Results are undefined if any of these functions are called with an +uninitialized read-write lock. +.P +If a signal is delivered to a thread waiting for a read-write lock for +writing, upon return from the signal handler the thread resumes waiting +for the read-write lock for writing as if it was not interrupted. +.SH "RETURN VALUE" +The +\fIpthread_rwlock_trywrlock\fR() +function shall return zero if the lock for writing on the read-write +lock object referenced by +.IR rwlock +is acquired. Otherwise, an error number shall be returned to indicate +the error. +.P +If successful, the +\fIpthread_rwlock_wrlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlock_trywrlock\fR() +function shall fail if: +.TP +.BR EBUSY +The read-write lock could not be acquired for writing because it was +already locked for reading or writing. +.P +The +\fIpthread_rwlock_wrlock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected or the current thread already owns +the read-write lock for writing or reading. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_trywrlock\fR() +or +\fIpthread_rwlock_wrlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_unlock.3p b/upstream/archlinux/man3p/pthread_rwlock_unlock.3p new file mode 100644 index 00000000..108a4684 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_unlock.3p @@ -0,0 +1,121 @@ +'\" et +.TH PTHREAD_RWLOCK_UNLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_unlock +\(em unlock a read-write lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_unlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlock_unlock\fR() +function shall release a lock held on the read-write lock object +referenced by +.IR rwlock . +Results are undefined if the read-write lock +.IR rwlock +is not held by the calling thread. +.P +If this function is called to release a read lock from the read-write +lock object and there are other read locks currently held on this +read-write lock object, the read-write lock object remains in the read +locked state. If this function releases the last read lock for this +read-write lock object, the read-write lock object shall be put in the +unlocked state with no owners. +.P +If this function is called to release a write lock for this read-write +lock object, the read-write lock object shall be put in the unlocked +state. +.P +If there are threads blocked on the lock when it becomes available, the +scheduling policy shall determine which thread(s) shall acquire the +lock. +If the Thread Execution Scheduling option is supported, when threads +executing with the scheduling policies SCHED_FIFO, SCHED_RR, or +SCHED_SPORADIC are waiting on the lock, they shall acquire the lock in +priority order when the lock becomes available. For equal priority +threads, write locks shall take precedence over read locks. +If the Thread Execution Scheduling option is not supported, it is +implementation-defined whether write locks take precedence over read +locks. +.P +Results are undefined if this function is called with an uninitialized +read-write lock. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlock_unlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlock_unlock\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_unlock\fR() +does not refer to an initialized read-write lock object, it is +recommended that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR rwlock +argument to +\fIpthread_rwlock_unlock\fR() +refers to a read-write lock object for which the current thread does +not hold a lock, it is recommended that the function should fail +and report an +.BR [EPERM] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlock_rdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)", +.IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)", +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlock_wrlock.3p b/upstream/archlinux/man3p/pthread_rwlock_wrlock.3p new file mode 100644 index 00000000..fd33ba9d --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlock_wrlock.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_RWLOCK_WRLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlock_wrlock +\(em lock a read-write lock object for writing +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlock_wrlock(pthread_rwlock_t *\fIrwlock\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlock_trywrlock\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlockattr_destroy.3p b/upstream/archlinux/man3p/pthread_rwlockattr_destroy.3p new file mode 100644 index 00000000..f6898809 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlockattr_destroy.3p @@ -0,0 +1,117 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlockattr_destroy, +pthread_rwlockattr_init +\(em destroy and initialize the read-write lock attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_destroy(pthread_rwlockattr_t *\fIattr\fP); +int pthread_rwlockattr_init(pthread_rwlockattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlockattr_destroy\fR() +function shall destroy a read-write lock attributes object. A destroyed +.IR attr +attributes object can be reinitialized using +\fIpthread_rwlockattr_init\fR(); +the results of otherwise referencing the object after it +has been destroyed are undefined. An implementation may cause +\fIpthread_rwlockattr_destroy\fR() +to set the object referenced by +.IR attr +to an invalid value. +.P +The +\fIpthread_rwlockattr_init\fR() +function shall initialize a read-write lock attributes object +.IR attr +with the default value for all of the attributes defined by the +implementation. +.P +Results are undefined if +\fIpthread_rwlockattr_init\fR() +is called specifying an already initialized +.IR attr +attributes object. +.P +After a read-write lock attributes object has been used to initialize +one or more read-write locks, any function affecting the attributes +object (including destruction) shall not affect any previously +initialized read-write locks. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_rwlockattr_destroy\fR() +does not refer to an initialized read-write lock attributes object. +.SH "RETURN VALUE" +If successful, the +\fIpthread_rwlockattr_destroy\fR() +and +\fIpthread_rwlockattr_init\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlockattr_init\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory exists to initialize the read-write lock attributes +object. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR attr +argument to +\fIpthread_rwlockattr_destroy\fR() +does not refer to an initialized read-write lock attributes object, +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlockattr_getpshared\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlockattr_getpshared.3p b/upstream/archlinux/man3p/pthread_rwlockattr_getpshared.3p new file mode 100644 index 00000000..1c8d6c67 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlockattr_getpshared.3p @@ -0,0 +1,122 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_GETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlockattr_getpshared, +pthread_rwlockattr_setpshared +\(em get and set the process-shared attribute of the read-write lock +attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t + *restrict \fIattr\fP, int *restrict \fIpshared\fP); +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_rwlockattr_getpshared\fR() +function shall obtain the value of the +.IR process-shared +attribute from the initialized attributes object referenced by +.IR attr . +The +\fIpthread_rwlockattr_setpshared\fR() +function shall set the +.IR process-shared +attribute in an initialized attributes object referenced by +.IR attr . +.P +The +.IR process-shared +attribute shall be set to PTHREAD_PROCESS_SHARED to +permit a read-write lock to be operated upon by any thread that has +access to the memory where the read-write lock is allocated, even if +the read-write lock is allocated in memory that is shared by multiple +processes. See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. The default value of the +.IR process-shared +attribute shall be PTHREAD_PROCESS_PRIVATE. +.P +Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +.P +The behavior is undefined if the value specified by the +.IR attr +argument to +\fIpthread_rwlockattr_getpshared\fR() +or +\fIpthread_rwlockattr_setpshared\fR() +does not refer to an initialized read-write lock attributes object. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_rwlockattr_getpshared\fR() +function shall return zero and store the value of the +.IR process-shared +attribute of +.IR attr +into the object referenced by the +.IR pshared +parameter. Otherwise, an error number shall be returned to indicate the +error. +.P +If successful, the +\fIpthread_rwlockattr_setpshared\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_rwlockattr_setpshared\fR() +function may fail if: +.TP +.BR EINVAL +The new value specified for the attribute is outside the range of legal +values for that attribute. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_rwlock_destroy\fR\^(\|)", +.IR "\fIpthread_rwlockattr_destroy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlockattr_init.3p b/upstream/archlinux/man3p/pthread_rwlockattr_init.3p new file mode 100644 index 00000000..aa6a9d86 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlockattr_init.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlockattr_init +\(em initialize the read-write lock attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_init(pthread_rwlockattr_t *\fIattr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlockattr_destroy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_rwlockattr_setpshared.3p b/upstream/archlinux/man3p/pthread_rwlockattr_setpshared.3p new file mode 100644 index 00000000..46a6ce06 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_rwlockattr_setpshared.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_RWLOCKATTR_SETPSHARED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_rwlockattr_setpshared +\(em set the process-shared attribute of the read-write lock +attributes object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *\fIattr\fP, + int \fIpshared\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_rwlockattr_getpshared\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_self.3p b/upstream/archlinux/man3p/pthread_self.3p new file mode 100644 index 00000000..2057f0f5 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_self.3p @@ -0,0 +1,69 @@ +'\" et +.TH PTHREAD_SELF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_self +\(em get the calling thread ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pthread_t pthread_self(void); +.fi +.SH DESCRIPTION +The +\fIpthread_self\fR() +function shall return the thread ID of the calling thread. +.SH "RETURN VALUE" +The +\fIpthread_self\fR() +function shall always be successful and no return value is +reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_self\fR() +function provides a capability similar to the +\fIgetpid\fR() +function for processes and the rationale is the same: the creation +call does not provide the thread ID to the created thread. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_create\fR\^(\|)", +.IR "\fIpthread_equal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_setcancelstate.3p b/upstream/archlinux/man3p/pthread_setcancelstate.3p new file mode 100644 index 00000000..aa969946 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_setcancelstate.3p @@ -0,0 +1,174 @@ +'\" et +.TH PTHREAD_SETCANCELSTATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_setcancelstate, +pthread_setcanceltype, +pthread_testcancel +\(em set cancelability state +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setcancelstate(int \fIstate\fP, int *\fIoldstate\fP); +int pthread_setcanceltype(int \fItype\fP, int *\fIoldtype\fP); +void pthread_testcancel(void); +.fi +.SH DESCRIPTION +The +\fIpthread_setcancelstate\fR() +function shall atomically both set the calling thread's cancelability +state to the indicated +.IR state +and return the previous cancelability state at the location referenced +by +.IR oldstate . +Legal values for +.IR state +are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE. +.P +The +\fIpthread_setcanceltype\fR() +function shall atomically both set the calling thread's cancelability +type to the indicated +.IR type +and return the previous cancelability type at the location referenced +by +.IR oldtype . +Legal values for +.IR type +are PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS. +.P +The cancelability state and type of any newly created threads, +including the thread in which +\fImain\fR() +was first invoked, shall be PTHREAD_CANCEL_ENABLE and +PTHREAD_CANCEL_DEFERRED respectively. +.P +The +\fIpthread_testcancel\fR() +function shall create a cancellation point in the calling thread. The +\fIpthread_testcancel\fR() +function shall have no effect if cancelability is disabled. +.SH "RETURN VALUE" +If successful, the +\fIpthread_setcancelstate\fR() +and +\fIpthread_setcanceltype\fR() +functions shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_setcancelstate\fR() +function may fail if: +.TP +.BR EINVAL +The specified state is not PTHREAD_CANCEL_ENABLE or +PTHREAD_CANCEL_DISABLE. +.P +The +\fIpthread_setcanceltype\fR() +function may fail if: +.TP +.BR EINVAL +The specified type is not PTHREAD_CANCEL_DEFERRED or +PTHREAD_CANCEL_ASYNCHRONOUS. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +In order to write a signal handler for an asynchronous signal which +can run safely in a cancellable thread, +\fIpthread_setcancelstate\fR() +must be used to disable cancellation for the duration of any calls +that the signal handler makes which are cancellation points. However, +the standard does not permit strictly conforming applications to call +\fIpthread_setcancelstate\fR() +from a signal handler since it is not currently required to be +async-signal-safe. On implementations where +\fIpthread_setcancelstate\fR() +is not async-signal-safe, alternatives are to ensure either that the +corresponding signals are blocked during execution of functions that +are not async-cancel-safe or that cancellation is disabled during +times when those signals could be delivered. Implementations are +strongly encouraged to make +\fIpthread_setcancelstate\fR() +async-signal-safe. +.SH RATIONALE +The +\fIpthread_setcancelstate\fR() +and +\fIpthread_setcanceltype\fR() +functions control the points at which a thread may be +asynchronously canceled. For cancellation control to be usable in +modular fashion, some rules need to be followed. +.P +An object can be considered to be a generalization of a procedure. It +is a set of procedures and global variables written as a unit and +called by clients not known by the object. Objects may depend on other +objects. +.P +First, cancelability should only be disabled on entry to an object, +never explicitly enabled. On exit from an object, the +cancelability state should always be restored to its value on entry to +the object. +.P +This follows from a modularity argument: if the client of an object +(or the client of an object that uses that object) has disabled +cancelability, it is because the client does not want to be concerned +about cleaning up if the thread is canceled while executing some +sequence of actions. If an object is called in such a state and it +enables cancelability and a cancellation request is pending for that +thread, then the thread is canceled, contrary to the wish of the client +that disabled. +.P +Second, the +cancelability type may be explicitly set to either +.IR deferred +or +.IR asynchronous +upon entry to an object. But as with the cancelability state, on exit +from an object the cancelability type should always be restored to its +value on entry to the object. +.P +Finally, only functions that are cancel-safe +may be called from a thread that is asynchronously cancelable. +.SH "FUTURE DIRECTIONS" +The +\fIpthread_setcancelstate\fR() +function may be added to the table of async-signal-safe functions in +.IR "Section 2.4.3" ", " "Signal Actions". +.SH "SEE ALSO" +.IR "\fIpthread_cancel\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_setconcurrency.3p b/upstream/archlinux/man3p/pthread_setconcurrency.3p new file mode 100644 index 00000000..cbd07055 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_setconcurrency.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_SETCONCURRENCY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_setconcurrency +\(em set the level of concurrency +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setconcurrency(int \fInew_level\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_getconcurrency\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_setschedparam.3p b/upstream/archlinux/man3p/pthread_setschedparam.3p new file mode 100644 index 00000000..3f85136a --- /dev/null +++ b/upstream/archlinux/man3p/pthread_setschedparam.3p @@ -0,0 +1,42 @@ +'\" et +.TH PTHREAD_SETSCHEDPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_setschedparam +\(em dynamic thread scheduling parameters access +(\fBREALTIME THREADS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setschedparam(pthread_t \fIthread\fP, int \fIpolicy\fP, + const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_getschedparam\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_setschedprio.3p b/upstream/archlinux/man3p/pthread_setschedprio.3p new file mode 100644 index 00000000..f427bdd8 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_setschedprio.3p @@ -0,0 +1,117 @@ +'\" et +.TH PTHREAD_SETSCHEDPRIO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_setschedprio +\(em dynamic thread scheduling parameters access +(\fBREALTIME THREADS\fR) +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setschedprio(pthread_t \fIthread\fP, int \fIprio\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_setschedprio\fR() +function shall set the scheduling priority for the thread whose thread +ID is given by +.IR thread +to the value given by +.IR prio . +See +.IR "Scheduling Policies" +for a description on how this function call affects the ordering of the +thread in the thread list for its new priority. +.P +If the +\fIpthread_setschedprio\fR() +function fails, the scheduling priority of the target thread shall not +be changed. +.SH "RETURN VALUE" +If successful, the +\fIpthread_setschedprio\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIpthread_setschedprio\fR() +function may fail if: +.TP +.BR EINVAL +The value of +.IR prio +is invalid for the scheduling policy of the specified thread. +.TP +.BR EPERM +The caller does not have appropriate privileges to set the scheduling +priority of the specified thread. +.P +The +\fIpthread_setschedprio\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIpthread_setschedprio\fR() +function provides a way for an application to temporarily raise its +priority and then lower it again, without having the undesired +side-effect of yielding to other threads of the same priority. This is +necessary if the application is to implement its own strategies for +bounding priority inversion, such as priority inheritance or priority +ceilings. This capability is especially important if the implementation +does not support the Thread Priority Protection or Thread Priority +Inheritance options, but even if those options are supported it is +needed if the application is to bound priority inheritance for other +resources, such as semaphores. +.P +The standard developers considered that while it might be preferable +conceptually to solve this problem by modifying the specification of +\fIpthread_setschedparam\fR(), +it was too late to make such a change, as there may be implementations +that would need to be changed. Therefore, this new function was +introduced. +.P +If an implementation detects use of a thread ID after the end of its +lifetime, it is recommended that the function should fail and report an +.BR [ESRCH] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Scheduling Policies", +.IR "\fIpthread_getschedparam\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_setspecific.3p b/upstream/archlinux/man3p/pthread_setspecific.3p new file mode 100644 index 00000000..4d7890a7 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_setspecific.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_SETSPECIFIC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_setspecific +\(em thread-specific data management +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_setspecific(pthread_key_t \fIkey\fP, const void *\fIvalue\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_getspecific\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_sigmask.3p b/upstream/archlinux/man3p/pthread_sigmask.3p new file mode 100644 index 00000000..4305e921 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_sigmask.3p @@ -0,0 +1,250 @@ +'\" et +.TH PTHREAD_SIGMASK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_sigmask, +sigprocmask +\(em examine and change blocked signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_sigmask(int \fIhow\fP, const sigset_t *restrict \fIset\fP, + sigset_t *restrict \fIoset\fP); +int sigprocmask(int \fIhow\fP, const sigset_t *restrict \fIset\fP, + sigset_t *restrict \fIoset\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_sigmask\fR() +function shall examine or change (or both) the calling thread's +signal mask, regardless of the number of threads in the process. The +function shall be equivalent to +\fIsigprocmask\fR(), +without the restriction that the call be made in a single-threaded +process. +.P +In a single-threaded process, the +\fIsigprocmask\fR() +function shall examine or change (or both) the signal mask of the +calling thread. +.P +If the argument +.IR set +is not a null pointer, it points to a set of signals to be used to +change the currently blocked set. +.P +The argument +.IR how +indicates the way in which the set is changed, and the application +shall ensure it consists of one of the following values: +.IP SIG_BLOCK 12 +The resulting set shall be the union of the current set and the signal +set pointed to by +.IR set . +.IP SIG_SETMASK 12 +The resulting set shall be the signal set pointed to by +.IR set . +.IP SIG_UNBLOCK 12 +The resulting set shall be the intersection of the current set and the +complement of the signal set pointed to by +.IR set . +.P +If the argument +.IR oset +is not a null pointer, the previous mask shall be stored in the location +pointed to by +.IR oset . +If +.IR set +is a null pointer, the value of the argument +.IR how +is not significant and the thread's signal mask shall be unchanged; +thus the call can be used to enquire about currently blocked signals. +.P +If there are any pending unblocked signals after the call to +\fIsigprocmask\fR(), +at least one of those signals shall be delivered before the call to +\fIsigprocmask\fR() +returns. +.P +It is not possible to block those signals which cannot be ignored. +This shall be enforced by the system without causing an error to be +indicated. +.P +If any of the SIGFPE, SIGILL, SIGSEGV, or SIGBUS +signals are generated while they are blocked, the result is undefined, +unless the signal was generated by the action of another process, or by +one of the functions +\fIkill\fR(), +\fIpthread_kill\fR(), +\fIraise\fR(), +or +\fIsigqueue\fR(). +.P +If +\fIsigprocmask\fR() +fails, the thread's signal mask shall not be changed. +.P +The use of the +\fIsigprocmask\fR() +function is unspecified in a multi-threaded process. +.SH "RETURN VALUE" +Upon successful completion +\fIpthread_sigmask\fR() +shall return 0; otherwise, it shall return the corresponding error +number. +.P +Upon successful completion, +\fIsigprocmask\fR() +shall return 0; otherwise, \-1 shall be returned, +.IR errno +shall be set to indicate the error, and the signal mask of the process +shall be unchanged. +.SH ERRORS +The +\fIpthread_sigmask\fR() +and +\fIsigprocmask\fR() +functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR how +argument is not equal to one of the defined values. +.P +The +\fIpthread_sigmask\fR() +function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Signaling in a Multi-Threaded Process" +.P +This example shows the use of +\fIpthread_sigmask\fR() +in order to deal with signals in a multi-threaded process. It provides +a fairly general framework that could be easily adapted/extended. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +\&... +.P +static sigset_t signal_mask; /* signals to block */ +.P +int main (int argc, char *argv[]) +{ + pthread_t sig_thr_id; /* signal handler thread ID */ + int rc; /* return code */ +.P + sigemptyset (&signal_mask); + sigaddset (&signal_mask, SIGINT); + sigaddset (&signal_mask, SIGTERM); + rc = pthread_sigmask (SIG_BLOCK, &signal_mask, NULL); + if (rc != 0) { + /* handle error */ + ... + } + /* any newly created threads inherit the signal mask */ +.P + rc = pthread_create (&sig_thr_id, NULL, signal_thread, NULL); + if (rc != 0) { + /* handle error */ + ... + } +.P + /* APPLICATION CODE */ + ... +} +.P +void *signal_thread (void *arg) +{ + int sig_caught; /* signal caught */ + int rc; /* returned code */ +.P + rc = sigwait (&signal_mask, &sig_caught); + if (rc != 0) { + /* handle error */ + } + switch (sig_caught) + { + case SIGINT: /* process SIGINT */ + ... + break; + case SIGTERM: /* process SIGTERM */ + ... + break; + default: /* should normally not happen */ + fprintf (stderr, "\enUnexpected signal %d\en", sig_caught); + break; + } +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +When a thread's signal mask is changed in a signal-catching function +that is installed by +\fIsigaction\fR(), +the restoration of the signal mask on return from the signal-catching +function overrides that change (see +\fIsigaction\fR()). +If the signal-catching function was installed with +\fIsignal\fR(), +it is unspecified whether this occurs. +.P +See +\fIkill\fR() +for a discussion of the requirement on delivery of signals. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigqueue\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_spin_destroy.3p b/upstream/archlinux/man3p/pthread_spin_destroy.3p new file mode 100644 index 00000000..e9e8ddb8 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_spin_destroy.3p @@ -0,0 +1,152 @@ +'\" et +.TH PTHREAD_SPIN_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_spin_destroy, +pthread_spin_init +\(em destroy or initialize a spin lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_spin_destroy(pthread_spinlock_t *\fIlock\fP); +int pthread_spin_init(pthread_spinlock_t *\fIlock\fP, int \fIpshared\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_spin_destroy\fR() +function shall destroy the spin lock referenced by +.IR lock +and release any resources used by the lock. The effect of subsequent +use of the lock is undefined until the lock is reinitialized by another +call to +\fIpthread_spin_init\fR(). +The results are undefined if +\fIpthread_spin_destroy\fR() +is called when a thread holds the lock, or if this function is called +with an uninitialized thread spin lock. +.P +The +\fIpthread_spin_init\fR() +function shall allocate any resources required to use the spin lock +referenced by +.IR lock +and initialize the lock to an unlocked state. +.P +If the Thread Process-Shared Synchronization option is supported and +the value of +.IR pshared +is PTHREAD_PROCESS_SHARED, the implementation +shall permit the spin lock to be operated upon by any thread that has +access to the memory where the spin lock is allocated, even if it is +allocated in memory that is shared by multiple processes. +.P +See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. +.P +The results are undefined if +\fIpthread_spin_init\fR() +is called specifying an already initialized spin lock. The results are +undefined if a spin lock is used without first being initialized. +.P +If the +\fIpthread_spin_init\fR() +function fails, the lock is not initialized and the contents of +.IR lock +are undefined. +.P +Only the object referenced by +.IR lock +may be used for performing synchronization. +.P +The result of referring to copies of that object in calls to +\fIpthread_spin_destroy\fR(), +\fIpthread_spin_lock\fR(), +\fIpthread_spin_trylock\fR(), +or +\fIpthread_spin_unlock\fR() +is undefined. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIpthread_spin_init\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacks the necessary resources to initialize another spin +lock. +.TP +.BR ENOMEM +Insufficient memory exists to initialize the lock. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_destroy\fR() +does not refer to an initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_destroy\fR() +or +\fIpthread_spin_init\fR() +refers to a locked spin lock object, or detects that the value specified +by the +.IR lock +argument to +\fIpthread_spin_init\fR() +refers to an already initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EBUSY] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIpthread_spin_lock\fR\^(\|)", +.IR "\fIpthread_spin_unlock\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_spin_lock.3p b/upstream/archlinux/man3p/pthread_spin_lock.3p new file mode 100644 index 00000000..d96312bf --- /dev/null +++ b/upstream/archlinux/man3p/pthread_spin_lock.3p @@ -0,0 +1,116 @@ +'\" et +.TH PTHREAD_SPIN_LOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_spin_lock, +pthread_spin_trylock +\(em lock a spin lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_spin_lock(pthread_spinlock_t *\fIlock\fP); +int pthread_spin_trylock(pthread_spinlock_t *\fIlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_spin_lock\fR() +function shall lock the spin lock referenced by +.IR lock . +The calling thread shall acquire the lock if it is not held by another +thread. Otherwise, the thread shall spin (that is, shall not return +from the +\fIpthread_spin_lock\fR() +call) until the lock becomes available. The results are undefined if +the calling thread holds the lock at the time the call is made. The +\fIpthread_spin_trylock\fR() +function shall lock the spin lock referenced by +.IR lock +if it is not held by any thread. Otherwise, the function shall fail. +.P +The results are undefined if any of these functions is called with an +uninitialized spin lock. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +.SH ERRORS +The +\fIpthread_spin_lock\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.P +The +\fIpthread_spin_trylock\fR() +function shall fail if: +.TP +.BR EBUSY +A thread currently holds the lock. +.P +These functions shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using this function may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_lock\fR() +or +\fIpthread_spin_trylock\fR() +does not refer to an initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_lock\fR() +refers to a spin lock object for which the calling thread already +holds the lock, it is recommended that the function should fail +and report an +.BR [EDEADLK] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_spin_destroy\fR\^(\|)", +.IR "\fIpthread_spin_unlock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_spin_unlock.3p b/upstream/archlinux/man3p/pthread_spin_unlock.3p new file mode 100644 index 00000000..308275de --- /dev/null +++ b/upstream/archlinux/man3p/pthread_spin_unlock.3p @@ -0,0 +1,100 @@ +'\" et +.TH PTHREAD_SPIN_UNLOCK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_spin_unlock +\(em unlock a spin lock object +.SH SYNOPSIS +.LP +.nf +#include +.P +int pthread_spin_unlock(pthread_spinlock_t *\fIlock\fP); +.fi +.SH DESCRIPTION +The +\fIpthread_spin_unlock\fR() +function shall release the spin lock referenced by +.IR lock +which was locked via the +\fIpthread_spin_lock\fR() +or +\fIpthread_spin_trylock\fR() +functions. +.P +The results are undefined if the lock is not held by the +calling thread. +.P +If there are threads spinning on the lock when +\fIpthread_spin_unlock\fR() +is called, the lock becomes available and an unspecified spinning +thread shall acquire the lock. +.P +The results are undefined if this function is called with an +uninitialized thread spin lock. +.SH "RETURN VALUE" +Upon successful completion, the +\fIpthread_spin_unlock\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +This function shall not return an error code of +.BR [EINTR] . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_unlock\fR() +does not refer to an initialized spin lock object, it is recommended +that the function should fail and report an +.BR [EINVAL] +error. +.P +If an implementation detects that the value specified by the +.IR lock +argument to +\fIpthread_spin_unlock\fR() +refers to a spin lock object for which the current thread does not +hold the lock, it is recommended that the function should fail +and report an +.BR [EPERM] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_spin_destroy\fR\^(\|)", +.IR "\fIpthread_spin_lock\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pthread_testcancel.3p b/upstream/archlinux/man3p/pthread_testcancel.3p new file mode 100644 index 00000000..956d3509 --- /dev/null +++ b/upstream/archlinux/man3p/pthread_testcancel.3p @@ -0,0 +1,40 @@ +'\" et +.TH PTHREAD_TESTCANCEL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pthread_testcancel +\(em set cancelability state +.SH SYNOPSIS +.LP +.nf +#include +.P +void pthread_testcancel(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_setcancelstate\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ptsname.3p b/upstream/archlinux/man3p/ptsname.3p new file mode 100644 index 00000000..c74c35db --- /dev/null +++ b/upstream/archlinux/man3p/ptsname.3p @@ -0,0 +1,104 @@ +'\" et +.TH PTSNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ptsname +\(em get name of the slave pseudo-terminal device +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ptsname(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIptsname\fR() +function shall return the name of the slave pseudo-terminal device +associated with a master pseudo-terminal device. The +.IR fildes +argument is a file descriptor that refers to the master device. The +\fIptsname\fR() +function shall return a pointer to a string containing the pathname +of the corresponding slave device. +.P +The +\fIptsname\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIptsname\fR() +shall return a pointer to a string which is the name of the +pseudo-terminal slave device. Upon failure, +\fIptsname\fR() +shall return a null pointer and may set +.IR errno . +This could occur if +.IR fildes +is an invalid file descriptor or if the slave device name does not +exist in the file system. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIptsname\fR(). +The returned pointer and the string content might also be invalidated +if the calling thread is terminated. +.SH ERRORS +The +\fIptsname\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a master pseudo-terminal device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIposix_openpt\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIttyname\fR\^(\|)", +.IR "\fIunlockpt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putc.3p b/upstream/archlinux/man3p/putc.3p new file mode 100644 index 00000000..863a506d --- /dev/null +++ b/upstream/archlinux/man3p/putc.3p @@ -0,0 +1,80 @@ +'\" et +.TH PUTC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putc +\(em put a byte on a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int putc(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIputc\fR() +function shall be equivalent to +\fIfputc\fR(), +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfputc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since it may be implemented as a macro, +\fIputc\fR() +may treat a +.IR stream +argument with side-effects incorrectly. In particular, +\fIputc\fP(\fIc\fP,*\fIf\fP++) does not necessarily work correctly. +Therefore, use of this function is not recommended in such situations; +\fIfputc\fR() +should be used instead. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putc_unlocked.3p b/upstream/archlinux/man3p/putc_unlocked.3p new file mode 100644 index 00000000..653de691 --- /dev/null +++ b/upstream/archlinux/man3p/putc_unlocked.3p @@ -0,0 +1,40 @@ +'\" et +.TH PUTC_UNLOCKED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putc_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int putc_unlocked(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetc_unlocked\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putchar.3p b/upstream/archlinux/man3p/putchar.3p new file mode 100644 index 00000000..e10c3b48 --- /dev/null +++ b/upstream/archlinux/man3p/putchar.3p @@ -0,0 +1,67 @@ +'\" et +.TH PUTCHAR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putchar +\(em put a byte on a stdout stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int putchar(int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The function call +.IR putchar ( c ) +shall be equivalent to \fIputc\fP(\fIc\fP,\fIstdout\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfputc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIputc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putchar_unlocked.3p b/upstream/archlinux/man3p/putchar_unlocked.3p new file mode 100644 index 00000000..a8fc0806 --- /dev/null +++ b/upstream/archlinux/man3p/putchar_unlocked.3p @@ -0,0 +1,40 @@ +'\" et +.TH PUTCHAR_UNLOCKED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putchar_unlocked +\(em stdio with explicit client locking +.SH SYNOPSIS +.LP +.nf +#include +.P +int putchar_unlocked(int \fIc\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetc_unlocked\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putenv.3p b/upstream/archlinux/man3p/putenv.3p new file mode 100644 index 00000000..4fcbfd1f --- /dev/null +++ b/upstream/archlinux/man3p/putenv.3p @@ -0,0 +1,161 @@ +'\" et +.TH PUTENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putenv +\(em change or add a value to an environment +.SH SYNOPSIS +.LP +.nf +#include +.P +int putenv(char *\fIstring\fP); +.fi +.SH DESCRIPTION +The +\fIputenv\fR() +function shall use the +.IR string +argument to set environment variable values. The +.IR string +argument should point to a string of the form "\c +.IR name =\c +.IR value \c +\&". +The +\fIputenv\fR() +function shall make the value of the environment variable +.IR name +equal to +.IR value +by altering an existing variable or creating a new one. In either +case, the string pointed to by +.IR string +shall become part of the environment, so altering the string shall +change the environment. +.P +The +\fIputenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIputenv\fR() +shall return 0; otherwise, it shall return a non-zero value and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIputenv\fR() +function may fail if: +.TP +.BR ENOMEM +Insufficient memory was available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Changing the Value of an Environment Variable" +.P +The following example changes the value of the +.IR HOME +environment variable to the value +.BR /usr/home . +.sp +.RS 4 +.nf + +#include +\&... +static char *var = "HOME=/usr/home"; +int ret; +.P +ret = putenv(var); +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputenv\fR() +function manipulates the environment pointed to by +.IR environ , +and can be used in conjunction with +\fIgetenv\fR(). +.P +See +\fIexec\fR() +for restrictions on changing the environment in multi-threaded +applications. +.P +This routine may use +\fImalloc\fR() +to enlarge the environment. +.P +A potential error is to call +\fIputenv\fR() +with an automatic variable as the argument, then return from the +calling function while +.IR string +is still part of the environment. +.P +Although the space used by +.IR string +is no longer used once a new string which defines +.IR name +is passed to +\fIputenv\fR(), +if any thread in the application has used +\fIgetenv\fR() +to retrieve a pointer to this variable, it should not be freed by calling +\fIfree\fR(). +If the changed environment variable is one known by the system (such as +the locale environment variables) the application should never free the +buffer used by earlier calls to +\fIputenv\fR() +for the same variable. +.P +The +\fIsetenv\fR() +function is preferred over this function. One reason is that +\fIputenv\fR() +is optional and therefore less portable. Another is that using +\fIputenv\fR() +can slow down environment searches, as explained in the RATIONALE +section for +.IR "\fIgetenv\fR\^(\|)". +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetenv\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putmsg.3p b/upstream/archlinux/man3p/putmsg.3p new file mode 100644 index 00000000..346f8e48 --- /dev/null +++ b/upstream/archlinux/man3p/putmsg.3p @@ -0,0 +1,363 @@ +'\" et +.TH PUTMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putmsg, +putpmsg +\(em send a message on a STREAM (\fBSTREAMS\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int putmsg(int \fIfildes\fP, const struct strbuf *\fIctlptr\fP, + const struct strbuf *\fIdataptr\fP, int \fIflags\fP); +int putpmsg(int \fIfildes\fP, const struct strbuf *\fIctlptr\fP, + const struct strbuf *\fIdataptr\fP, int \fIband\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIputmsg\fR() +function shall create a message from a process buffer(s) and send the +message to a STREAMS file. The message may contain either a data part, +a control part, or both. The data and control parts are distinguished +by placement in separate buffers, as described below. The semantics of +each part are defined by the STREAMS module that receives the message. +.P +The +\fIputpmsg\fR() +function is equivalent to +\fIputmsg\fR(), +except that the process can send messages in different priority bands. +Except where noted, all requirements on +\fIputmsg\fR() +also pertain to +\fIputpmsg\fR(). +.P +The +.IR fildes +argument specifies a file descriptor referencing an open STREAM. The +.IR ctlptr +and +.IR dataptr +arguments each point to a +.BR strbuf +structure. +.P +The +.IR ctlptr +argument points to the structure describing the control part, if any, +to be included in the message. The +.IR buf +member in the +.BR strbuf +structure points to the buffer where the control information resides, +and the +.IR len +member indicates the number of bytes to be sent. The +.IR maxlen +member is not used by +\fIputmsg\fR(). +In a similar manner, the argument +.IR dataptr +specifies the data, if any, to be included in the message. The +.IR flags +argument indicates what type of message should be sent and is described +further below. +.P +To send the data part of a message, the application shall ensure that +.IR dataptr +is not a null pointer and the +.IR len +member of +.IR dataptr +is 0 or greater. To send the control part of a message, the application +shall ensure that the corresponding values are set for +.IR ctlptr . +No data (control) part shall be sent if either +.IR dataptr (\c +.IR ctlptr ) +is a null pointer or the +.IR len +member of +.IR dataptr (\c +.IR ctlptr ) +is set to \-1. +.P +For +\fIputmsg\fR(), +if a control part is specified and +.IR flags +is set to RS_HIPRI, a high +priority message shall be sent. If no control part is specified, and +.IR flags +is set to RS_HIPRI, +\fIputmsg\fR() +shall fail and set +.IR errno +to +.BR [EINVAL] . +If +.IR flags +is set to 0, a normal message (priority band equal to 0) shall be sent. +If a control part and data part are not specified and +.IR flags +is set to 0, no message shall be sent and 0 shall be returned. +.P +For +\fIputpmsg\fR(), +the flags are different. The +.IR flags +argument is a bitmask with the following mutually-exclusive flags +defined: MSG_HIPRI and MSG_BAND. If +.IR flags +is set to 0, +\fIputpmsg\fR() +shall fail and set +.IR errno +to +.BR [EINVAL] . +If a control part is specified and +.IR flags +is set to MSG_HIPRI and +.IR band +is set to 0, a high-priority message shall be sent. If +.IR flags +is set to MSG_HIPRI and either no control part is specified or +.IR band +is set to a non-zero value, +\fIputpmsg\fR() +shall fail and set +.IR errno +to +.BR [EINVAL] . +If +.IR flags +is set to MSG_BAND, then a message shall be sent in the priority band +specified by +.IR band . +If a control part and data part are not specified and +.IR flags +is set to MSG_BAND, no message shall be sent and 0 shall be returned. +.br +.P +The +\fIputmsg\fR() +function shall block if the STREAM write queue is full due to internal +flow control conditions, with the following exceptions: +.IP " *" 4 +For high-priority messages, +\fIputmsg\fR() +shall not block on this condition and continues processing the message. +.IP " *" 4 +For other messages, +\fIputmsg\fR() +shall not block but shall fail when the write queue is full and +O_NONBLOCK is set. +.P +The +\fIputmsg\fR() +function shall also block, unless prevented by lack of internal +resources, while waiting for the availability of message blocks in the +STREAM, regardless of priority or whether O_NONBLOCK has been +specified. No partial message shall be sent. +.SH "RETURN VALUE" +Upon successful completion, +\fIputmsg\fR() +and +\fIputpmsg\fR() +shall return 0; otherwise, they shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIputmsg\fR() +and +\fIputpmsg\fR() +functions shall fail if: +.TP +.BR EAGAIN +A non-priority message was specified, the O_NONBLOCK flag is set, and +the STREAM write queue is full due to internal flow control conditions; +or buffers could not be allocated for the message that was to be +created. +.TP +.BR EBADF +.IR fildes +is not a valid file descriptor open for writing. +.TP +.BR EINTR +A signal was caught during +\fIputmsg\fR(). +.TP +.BR EINVAL +An undefined value is specified in +.IR flags , +or +.IR flags +is set to RS_HIPRI or MSG_HIPRI and no control part is supplied, or the +STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer, or +.IR flags +is set to MSG_HIPRI and +.IR band +is non-zero (for +\fIputpmsg\fR() +only). +.TP +.BR ENOSR +Buffers could not be allocated for the message that was to be created +due to insufficient STREAMS memory resources. +.TP +.BR ENOSTR +A STREAM is not associated with +.IR fildes . +.TP +.BR ENXIO +A hangup condition was generated downstream for the specified STREAM. +.TP +.BR EPIPE " or " EIO +The +.IR fildes +argument refers to a STREAMS-based pipe and the other end of the pipe +is closed. A SIGPIPE signal is generated for the calling thread. +.TP +.BR ERANGE +The size of the data part of the message does not fall within the range +specified by the maximum and minimum packet sizes of the topmost STREAM +module. This value is also returned if the control part of the message +is larger than the maximum configured size of the control part of a +message, or if the data part of a message is larger than the maximum +configured size of the data part of a message. +.P +In addition, +\fIputmsg\fR() +and +\fIputpmsg\fR() +shall fail if the STREAM head had processed an asynchronous error +before the call. In this case, the value of +.IR errno +does not reflect the result of +\fIputmsg\fR() +or +\fIputpmsg\fR(), +but reflects the prior error. +.br +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Sending a High-Priority Message" +.P +The value of +.IR fd +is assumed to refer to an open STREAMS file. This call to +\fIputmsg\fR() +does the following: +.IP " 1." 4 +Creates a high-priority message with a control part and a data part, +using the buffers pointed to by +.IR ctrlbuf +and +.IR databuf , +respectively. +.IP " 2." 4 +Sends the message to the STREAMS file identified by +.IR fd . +.sp +.RS 4 +.nf + +#include +#include +\&... +int fd; +char *ctrlbuf = "This is the control part"; +char *databuf = "This is the data part"; +struct strbuf ctrl; +struct strbuf data; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.len = strlen(ctrlbuf); +.P +data.buf = databuf; +data.len = strlen(databuf); +.P +ret = putmsg(fd, &ctrl, &data, MSG_HIPRI); +.fi +.P +.RE +.SS "Using putpmsg(\|)" +.P +This example has the same effect as the previous example. In this +example, however, the +\fIputpmsg\fR() +function creates and sends the message to the STREAMS file. +.sp +.RS 4 +.nf + +#include +#include +\&... +int fd; +char *ctrlbuf = "This is the control part"; +char *databuf = "This is the data part"; +struct strbuf ctrl; +struct strbuf data; +int ret; +.P +ctrl.buf = ctrlbuf; +ctrl.len = strlen(ctrlbuf); +.P +data.buf = databuf; +data.len = strlen(databuf); +.P +ret = putpmsg(fd, &ctrl, &data, 0, MSG_HIPRI); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIputmsg\fR() +and +\fIputpmsg\fR() +functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.6" ", " "STREAMS", +.IR "\fIgetmsg\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/puts.3p b/upstream/archlinux/man3p/puts.3p new file mode 100644 index 00000000..309f4169 --- /dev/null +++ b/upstream/archlinux/man3p/puts.3p @@ -0,0 +1,147 @@ +'\" et +.TH PUTS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +puts +\(em put a string on standard output +.SH SYNOPSIS +.LP +.nf +#include +.P +int puts(const char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIputs\fR() +function shall write the string pointed to by +.IR s , +followed by a +, +to the standard output stream +.IR stdout . +The terminating null byte shall not be written. +.P +The last data modification and last file status change timestamps +of the file shall be marked for update between the successful +execution of +\fIputs\fR() +and the next successful completion of a call to +\fIfflush\fR() +or +\fIfclose\fR() +on the same stream or a call to +\fIexit\fR() +or +\fIabort\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fIputs\fR() +shall return a non-negative number. Otherwise, it shall return EOF, +shall set an error indicator for the stream, +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +Refer to +.IR "\fIfputc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Printing to Standard Output" +.P +The following example gets the current time, converts it to a string +using +\fIlocaltime\fR() +and +\fIasctime\fR(), +and prints it to standard output using +\fIputs\fR(). +It then prints the number of minutes to an event for which it is +waiting. +.sp +.RS 4 +.nf + +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +printf("The time is "); +puts(asctime(localtime(&now))); +printf("There are %d minutes to the event.\en", + minutes_to_event); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIputs\fR() +function appends a +, +while +\fIfputs\fR() +does not. +.P +This volume of POSIX.1\(hy2017 requires that successful completion simply return a non-negative +integer. There are at least three known different implementation +conventions for this requirement: +.IP " *" 4 +Return a constant value. +.IP " *" 4 +Return the last character written. +.IP " *" 4 +Return the number of bytes written. Note that this implementation +convention cannot be adhered to for strings longer than +{INT_MAX} +bytes as the value would not be representable in the return type of the +function. For backwards compatibility, implementations can return the +number of bytes for strings of up to +{INT_MAX} +bytes, and return +{INT_MAX} +for all longer strings. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfputs\fR\^(\|)", +.IR "\fIputc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pututxline.3p b/upstream/archlinux/man3p/pututxline.3p new file mode 100644 index 00000000..25c884bb --- /dev/null +++ b/upstream/archlinux/man3p/pututxline.3p @@ -0,0 +1,40 @@ +'\" et +.TH PUTUTXLINE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pututxline +\(em put an entry into the user accounting database +.SH SYNOPSIS +.LP +.nf +#include +.P +struct utmpx *pututxline(const struct utmpx *\fIutmpx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendutxent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putwc.3p b/upstream/archlinux/man3p/putwc.3p new file mode 100644 index 00000000..f19e963f --- /dev/null +++ b/upstream/archlinux/man3p/putwc.3p @@ -0,0 +1,82 @@ +'\" et +.TH PUTWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putwc +\(em put a wide character on a stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t putwc(wchar_t \fIwc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIputwc\fR() +function shall be equivalent to +\fIfputwc\fR(), +except that if it is implemented as a macro it may evaluate +.IR stream +more than once, so the argument should never be an expression with +side-effects. +.SH "RETURN VALUE" +Refer to +.IR "\fIfputwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since it may be implemented as a macro, +\fIputwc\fR() +may treat a +.IR stream +argument with side-effects incorrectly. In particular, +\fIputwc\fP(\fIwc\fP,*\fIf\fP++) need not work correctly. Therefore, +use of this function is not recommended; +\fIfputwc\fR() +should be used instead. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/putwchar.3p b/upstream/archlinux/man3p/putwchar.3p new file mode 100644 index 00000000..803840ce --- /dev/null +++ b/upstream/archlinux/man3p/putwchar.3p @@ -0,0 +1,68 @@ +'\" et +.TH PUTWCHAR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +putwchar +\(em put a wide character on a stdout stream +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t putwchar(wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The function call +.IR putwchar ( wc ) +shall be equivalent to \fIputwc\fP(\fIwc\fP,\fIstdout\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIfputwc\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfputwc\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfputwc\fR\^(\|)", +.IR "\fIputwc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/pwrite.3p b/upstream/archlinux/man3p/pwrite.3p new file mode 100644 index 00000000..a21a8eda --- /dev/null +++ b/upstream/archlinux/man3p/pwrite.3p @@ -0,0 +1,41 @@ +'\" et +.TH PWRITE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pwrite +\(em write on a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pwrite(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP, + off_t \fIoffset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwrite\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/qsort.3p b/upstream/archlinux/man3p/qsort.3p new file mode 100644 index 00000000..15b8f241 --- /dev/null +++ b/upstream/archlinux/man3p/qsort.3p @@ -0,0 +1,115 @@ +'\" et +.TH QSORT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +qsort +\(em sort a table of data +.SH SYNOPSIS +.LP +.nf +#include +.P +void qsort(void *\fIbase\fP, size_t \fInel\fP, size_t \fIwidth\fP, + int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIqsort\fR() +function shall sort an array of +.IR nel +objects, the initial element of which is pointed to by +.IR base . +The size of each object, in bytes, is specified by the +.IR width +argument. If the +.IR nel +argument has the value zero, the comparison function pointed to by +.IR compar +shall not be called and no rearrangement shall take place. +.P +The application shall ensure that the comparison function pointed to by +.IR compar +does not alter the contents of the array. The implementation may +reorder elements of the array between calls to the comparison function, +but shall not alter the contents of any individual element. +.P +When the same objects (consisting of width bytes, irrespective of their +current positions in the array) are passed more than once to the +comparison function, the results shall be consistent with one another. +That is, they shall define a total ordering on the array. +.P +The contents of the array shall be sorted in ascending order according +to a comparison function. The +.IR compar +argument is a pointer to the comparison function, which is called with +two arguments that point to the elements being compared. The +application shall ensure that the function returns an integer less +than, equal to, or greater than 0, if the first argument is considered +respectively less than, equal to, or greater than the second. If two +members compare as equal, their order in the sorted array is +unspecified. +.SH "RETURN VALUE" +The +\fIqsort\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The comparison function need not compare every byte, so arbitrary data +may be contained in the elements in addition to the values being +compared. +.SH RATIONALE +The requirement that each argument (hereafter referred to as +.IR p) +to the comparison function is a pointer to elements of the array +implies that for every call, for each argument separately, all of the +following expressions are non-zero: +.sp +.RS 4 +.nf + +((char *)p - (char *)base) % width == 0 +(char *)p >= (char *)base +(char *)p < (char *)base + nel * width +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalphasort\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/raise.3p b/upstream/archlinux/man3p/raise.3p new file mode 100644 index 00000000..f761bb19 --- /dev/null +++ b/upstream/archlinux/man3p/raise.3p @@ -0,0 +1,95 @@ +'\" et +.TH RAISE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +raise +\(em send a signal to the executing process +.SH SYNOPSIS +.LP +.nf +#include +.P +int raise(int \fIsig\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIraise\fR() +function shall send the signal +.IR sig +to the executing +thread or process. +If a signal handler is called, the +\fIraise\fR() +function shall not return until after the signal handler does. +.P +The effect of the +\fIraise\fR() +function shall be equivalent to calling: +.sp +.RS 4 +.nf + +pthread_kill(pthread_self(), sig); +.fi +.P +.RE +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, a +non-zero value shall be returned +and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIraise\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR sig +argument is an invalid signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The term ``thread'' is an extension to the ISO\ C standard. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIkill\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/rand.3p b/upstream/archlinux/man3p/rand.3p new file mode 100644 index 00000000..63c9cdf3 --- /dev/null +++ b/upstream/archlinux/man3p/rand.3p @@ -0,0 +1,231 @@ +'\" et +.TH RAND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +rand, +rand_r, +srand +\(em pseudo-random number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +int rand(void); +int rand_r(unsigned *\fIseed\fP); +void srand(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +For +\fIrand\fR() +and +\fIsrand\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIrand\fR() +function shall compute a sequence of pseudo-random integers in the +range [0,\c +{RAND_MAX}] +with a period of at least 2\u\s-332\s0\d. +.P +The +\fIrand\fR() +function need not be thread-safe. +.P +The +\fIrand_r\fR() +function shall compute a sequence of pseudo-random integers in +the range [0,\c +{RAND_MAX}]. +(The value of the +{RAND_MAX} +macro shall be at least 32\|767.) +.P +If +\fIrand_r\fR() +is called with the same initial value for the object pointed to by +.IR seed +and that object is not modified between successive returns and calls to +\fIrand_r\fR(), +the same sequence shall be generated. +.P +The +\fIsrand\fR() +function uses the argument as a seed for a new sequence of +pseudo-random numbers to be returned by subsequent calls to +\fIrand\fR(). +If +\fIsrand\fR() +is then called with the same seed value, the sequence of pseudo-random +numbers shall be repeated. If +\fIrand\fR() +is called before any calls to +\fIsrand\fR() +are made, the same sequence shall be generated as when +\fIsrand\fR() +is first called with a seed value of 1. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 +calls +\fIrand\fR() +or +\fIsrand\fR(). +.SH "RETURN VALUE" +The +\fIrand\fR() +function shall return the next pseudo-random number in the sequence. +.P +The +\fIrand_r\fR() +function shall return a pseudo-random integer. +.P +The +\fIsrand\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pseudo-Random Number Sequence" +.P +The following example demonstrates how to generate a sequence of +pseudo-random numbers. +.sp +.RS 4 +.nf + +#include +#include +\&... + long count, i; + char *keystr; + int elementlen, len; + char c; +\&... +/* Initial random number generator. */ + srand(1); +.P + /* Create keys using only lowercase characters */ + len = 0; + for (i=0; i\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/random.3p b/upstream/archlinux/man3p/random.3p new file mode 100644 index 00000000..57311300 --- /dev/null +++ b/upstream/archlinux/man3p/random.3p @@ -0,0 +1,40 @@ +'\" et +.TH RANDOM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +random +\(em generate pseudo-random number +.SH SYNOPSIS +.LP +.nf +#include +.P +long random(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinitstate\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/read.3p b/upstream/archlinux/man3p/read.3p new file mode 100644 index 00000000..07462d9d --- /dev/null +++ b/upstream/archlinux/man3p/read.3p @@ -0,0 +1,628 @@ +'\" et +.TH READ "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pread, +read +\(em read from a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pread(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP, off_t \fIoffset\fR); +ssize_t read(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP); +.fi +.SH DESCRIPTION +The +\fIread\fR() +function shall attempt to read +.IR nbyte +bytes from the file associated with the open file descriptor, +.IR fildes , +into the buffer pointed to by +.IR buf . +The behavior of multiple concurrent reads on the same pipe, FIFO, or +terminal device is unspecified. +.P +Before any action described below is taken, and if +.IR nbyte +is zero, the +\fIread\fR() +function may detect and return errors as described below. In the +absence of errors, or if error detection is not performed, the +\fIread\fR() +function shall return zero and have no other results. +.P +On files that support seeking (for example, a regular file), the +\fIread\fR() +shall start at a position in the file given by the file offset +associated with +.IR fildes . +The file offset shall be incremented by the number of bytes +actually read. +.P +Files that do not support seeking\(emfor example, terminals\(emalways +read from the current position. The value of a file offset associated +with such a file is undefined. +.P +No data transfer shall occur past the current end-of-file. If the +starting position is at or after the end-of-file, 0 shall be returned. +If the file refers to a device special file, the result of subsequent +\fIread\fR() +requests is implementation-defined. +.P +If the value of +.IR nbyte +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +When attempting to read from an empty pipe or FIFO: +.IP " *" 4 +If no process has the pipe open for writing, +\fIread\fR() +shall return 0 to indicate end-of-file. +.IP " *" 4 +If some process has the pipe open for writing and O_NONBLOCK is set, +\fIread\fR() +shall return \-1 and set +.IR errno +to +.BR [EAGAIN] . +.IP " *" 4 +If some process has the pipe open for writing and O_NONBLOCK is clear, +\fIread\fR() +shall block the calling thread until some data is written or the pipe +is closed by all processes that had the pipe open for writing. +.P +When attempting to read a file (other than a pipe or FIFO) that +supports non-blocking reads and has no data currently available: +.IP " *" 4 +If O_NONBLOCK is set, +\fIread\fR() +shall return \-1 and set +.IR errno +to +.BR [EAGAIN] . +.IP " *" 4 +If O_NONBLOCK is clear, +\fIread\fR() +shall block the calling thread until some data becomes available. +.IP " *" 4 +The use of the O_NONBLOCK flag has no effect if there is some data +available. +.P +The +\fIread\fR() +function reads data previously written to a file. If any portion of a +regular file prior to the end-of-file has not been written, +\fIread\fR() +shall return bytes with value 0. For example, +\fIlseek\fR() +allows the file offset to be set beyond the end of existing data in the +file. If data is later written at this point, subsequent reads in the +gap between the previous end of data and the newly written data shall +return bytes with value 0 until data is written into the gap. +.P +Upon successful completion, where +.IR nbyte +is greater than 0, +\fIread\fR() +shall mark for update the last data access timestamp +of the file, and shall return the number of bytes read. +This number shall never be greater than +.IR nbyte . +The value returned may be less than +.IR nbyte +if the number of bytes left in the file is less than +.IR nbyte , +if the +\fIread\fR() +request was interrupted by a signal, or if the file is a pipe or FIFO +or special file and has fewer than +.IR nbyte +bytes immediately available for reading. For example, a +\fIread\fR() +from a file associated with a terminal may return one typed line of +data. +.P +If a +\fIread\fR() +is interrupted by a signal before it reads any data, it shall return +\-1 with +.IR errno +set to +.BR [EINTR] . +.P +If a +\fIread\fR() +is interrupted by a signal after it has successfully read some data, it +shall return the number of bytes read. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +.IR fildes . +.P +If +.IR fildes +refers to a socket, +\fIread\fR() +shall be equivalent to +\fIrecv\fR() +with no flags set. +.P +If the O_DSYNC and O_RSYNC bits have been set, +read I/O operations on the file descriptor shall complete as defined by +synchronized I/O data integrity completion. If the O_SYNC and O_RSYNC +bits have been set, read I/O operations on the file descriptor shall +complete as defined by synchronized I/O file integrity completion. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIread\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIread\fR() +function is unspecified. +.P +A +\fIread\fR() +from a STREAMS file can read data in three different modes: +\fIbyte-stream\fP mode, \fImessage-nondiscard\fP mode, and +\fImessage-discard\fP mode. The default shall be byte-stream mode. +This can be changed using the I_SRDOPT +\fIioctl\fR() +request, and can be tested with I_GRDOPT +\fIioctl\fR(). +In byte-stream mode, +\fIread\fR() +shall retrieve data from the STREAM until as many bytes as were +requested are +transferred, or until there is no more data to be retrieved. +Byte-stream mode ignores message boundaries. +.P +In STREAMS message-nondiscard mode, +\fIread\fR() +shall retrieve data until as many bytes as were requested are +transferred, or until a message boundary is reached. If +\fIread\fR() +does not retrieve all the data in a message, the remaining data shall +be left on the STREAM, and can be retrieved by the next +\fIread\fR() +call. Message-discard mode also retrieves data until as many bytes as +were requested are transferred, or a message boundary is reached. +However, unread data remaining in a message after the +\fIread\fR() +returns shall be discarded, and shall not be available for a subsequent +\fIread\fR(), +\fIgetmsg\fR(), +or +\fIgetpmsg\fR() +call. +.P +How +\fIread\fR() +handles zero-byte STREAMS messages is determined by the current read +mode setting. In byte-stream mode, +\fIread\fR() +shall accept data until it has read +.IR nbyte +bytes, or until there is no more data to read, or until a zero-byte +message block is encountered. The +\fIread\fR() +function shall then return the number of bytes read, and place the +zero-byte message back on the STREAM to be retrieved by the next +\fIread\fR(), +\fIgetmsg\fR(), +or +\fIgetpmsg\fR(). +In message-nondiscard mode or message-discard mode, a zero-byte message +shall return 0 and the message shall be removed from the STREAM. When a +zero-byte message is read as the first message on a STREAM, the message +shall be removed from the STREAM and 0 shall be returned, regardless of +the read mode. +.P +A +\fIread\fR() +from a STREAMS file shall return the data in the message at the front +of the STREAM head read queue, regardless of the priority band of the +message. +.P +By default, STREAMs are in control-normal mode, in which a +\fIread\fR() +from a STREAMS file can only process messages that contain a data part +but do not contain a control part. The +\fIread\fR() +shall fail if a message containing a control part is encountered at the +STREAM head. This default action can be changed by placing the STREAM +in either control-data mode or control-discard mode with the I_SRDOPT +\fIioctl\fR() +command. In control-data mode, +\fIread\fR() +shall convert any control part to data and pass it to the application +before passing any data part originally present in the same message. +In control-discard mode, +\fIread\fR() +shall discard message control parts but return to the process any data +part in the message. +.P +In addition, +\fIread\fR() +shall fail if the STREAM head had processed an asynchronous error +before the call. In this case, the value of +.IR errno +shall not reflect the result of +\fIread\fR(), +but reflect the prior error. If a hangup occurs on the STREAM being +read, +\fIread\fR() +shall continue to operate normally until the STREAM head read queue is +empty. Thereafter, it shall return 0. +.P +The +\fIpread\fR() +function shall be equivalent to +\fIread\fR(), +except that it shall read from a given position in the file without +changing the file offset. The first three arguments to +\fIpread\fR() +are the same as +\fIread\fR() +with the addition of a fourth argument +.IR offset +for the desired position inside the file. An attempt to perform a +\fIpread\fR() +on a file that is incapable of seeking shall result in an error. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return a non-negative +integer indicating the number of bytes actually read. Otherwise, the +functions shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EAGAIN +The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK +flag is set for the file descriptor, and the thread would be delayed +in the read operation. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor open for reading. +.TP +.BR EBADMSG +The file is a STREAM file that is set to control-normal mode and the +message waiting to be read includes a control part. +.TP +.BR EINTR +The read operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EINVAL +The STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.TP +.BR EIO +The process is a member of a background process group attempting to read +from its controlling terminal, and either the calling thread is blocking +SIGTTIN or the process is ignoring SIGTTIN or the process group of the +process is orphaned. This error may also be generated for +implementation-defined reasons. +.TP +.BR EISDIR +The +.IR fildes +argument refers to a directory and the implementation +does not allow the directory to be read using +\fIread\fR() +or +\fIpread\fR(). +The +\fIreaddir\fR() +function should be used instead. +.TP +.BR EOVERFLOW +The file is a regular file, +.IR nbyte +is greater than 0, the starting position is before the end-of-file, and +the starting position is greater than or equal to the offset maximum +established in the open file description associated with +.IR fildes . +.P +The +\fIpread\fR() +function shall fail if: +.TP +.BR EINVAL +The file is a regular file or block special file, and the +.IR offset +argument is negative. The file offset shall remain unchanged. +.TP +.BR ESPIPE +The file is incapable of seeking. +.br +.P +The +\fIread\fR() +function shall fail if: +.TP +.BR EAGAIN +The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the read operation. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The file is a socket, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the read operation. +.TP +.BR ECONNRESET +A read was attempted on a socket and the connection was forcibly closed +by its peer. +.TP +.BR ENOTCONN +A read was attempted on a socket that is not connected. +.TP +.BR ETIMEDOUT +A read was attempted on a socket and a transmission timeout occurred. +.P +These functions may fail if: +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading Data into a Buffer" +.P +The following example reads data from the file associated with the file +descriptor +.IR fd +into the buffer pointed to by +.IR buf . +.sp +.RS 4 +.nf + +#include +#include +\&... +char buf[20]; +size_t nbytes; +ssize_t bytes_read; +int fd; +\&... +nbytes = sizeof(buf); +bytes_read = read(fd, buf, nbytes); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +This volume of POSIX.1\(hy2017 does not specify the value of the file offset after an +error is returned; there are too many cases. For programming errors, +such as +.BR [EBADF] , +the concept is meaningless since no file is involved. For errors that +are detected immediately, such as +.BR [EAGAIN] , +clearly the offset should not change. After an interrupt or hardware +error, however, an updated value would be very useful and is the +behavior of many implementations. +.P +Note that a +\fIread\fR() +of zero bytes does not modify the last data access timestamp. A +\fIread\fR() +that requests more than zero bytes, but returns zero, is required +to modify the last data access timestamp. +.P +Implementations are allowed, but not required, to perform error +checking for +\fIread\fR() +requests of zero bytes. +.SS "Input and Output" +.P +The use of I/O with large byte counts has always presented problems. +Ideas such as +\fIlread\fR() +and +\fIlwrite\fR() +(using and returning +.BR long s) +were considered at one time. The current solution is to use abstract +types on the ISO\ C standard function to +\fIread\fR() +and +\fIwrite\fR(). +The abstract types can be declared so that existing functions work, but +can also be declared so that larger types can be represented in future +implementations. It is presumed that whatever constraints limit the +maximum range of +.BR size_t +also limit portable I/O requests to the same range. This volume of POSIX.1\(hy2017 also limits +the range further by requiring that the byte count be limited so that a +signed return value remains meaningful. Since the return type is also a +(signed) abstract type, the byte count can be defined by the +implementation to be larger than an +.BR int +can hold. +.P +The standard developers considered adding atomicity requirements to a +pipe or FIFO, but recognized that due to the nature of pipes and FIFOs +there could be no guarantee of atomicity of reads of +{PIPE_BUF} +or any other size that would be an aid to applications portability. +.P +This volume of POSIX.1\(hy2017 requires that no action be taken for +\fIread\fR() +or +\fIwrite\fR() +when +.IR nbyte +is zero. This is not intended to take precedence over detection of +errors (such as invalid buffer pointers or file descriptors). This is +consistent with the rest of this volume of POSIX.1\(hy2017, but the phrasing here could be +misread to require detection of the zero case before any other errors. +A value of zero is to be considered a correct value, for which the +semantics are a no-op. +.P +I/O is intended to be atomic to ordinary files and pipes and FIFOs. +Atomic means that all the bytes from a single operation that +started out together end up together, without interleaving from other +I/O operations. It is a known attribute of terminals that this is not +honored, and terminals are explicitly (and implicitly permanently) +excepted, making the behavior unspecified. The behavior for other +device types is also left unspecified, but the wording is intended to +imply that future standards might choose to specify atomicity (or not). +.P +There were recommendations to add format parameters to +\fIread\fR() +and +\fIwrite\fR() +in order to handle networked transfers among heterogeneous file system +and base hardware types. Such a facility may be required for support by +the OSI presentation of layer services. However, it was determined that +this should correspond with similar C-language facilities, and that is +beyond the scope of this volume of POSIX.1\(hy2017. The concept was suggested to the developers +of the ISO\ C standard for their consideration as a possible area for future +work. +.P +In 4.3 BSD, a +\fIread\fR() +or +\fIwrite\fR() +that is interrupted by a signal before transferring any data does not +by default return an +.BR [EINTR] +error, but is restarted. In 4.2 BSD, +4.3 BSD, +and the Eighth Edition, there is an additional function, +\fIselect\fR(), +whose purpose is to pause until specified activity (data to read, space +to write, and so on) is detected on specified file descriptors. It is +common in applications written for those systems for +\fIselect\fR() +to be used before +\fIread\fR() +in situations (such as keyboard input) where interruption of I/O due to +a signal is desired. +.P +The issue of which files or file types are interruptible is considered +an implementation design issue. This is often affected primarily by +hardware and reliability issues. +.P +There are no references to actions taken following an ``unrecoverable +error''. It is considered beyond the scope of this volume of POSIX.1\(hy2017 to describe what +happens in the case of hardware errors. +.P +Earlier versions of this standard allowed two very different behaviors +with regard to the handling of interrupts. In order to minimize the +resulting confusion, it was decided that POSIX.1\(hy2008 should support only one +of these behaviors. Historical practice on AT&T-derived systems was to +have +\fIread\fR() +and +\fIwrite\fR() +return \-1 and set +.IR errno +to +.BR [EINTR] +when interrupted after some, but not all, of the data requested had +been transferred. However, the US Department of Commerce FIPS 151\(hy1 and +FIPS 151\(hy2 require the historical BSD behavior, in which +\fIread\fR() +and +\fIwrite\fR() +return the number of bytes actually transferred before the interrupt. +If \-1 is returned when any data is transferred, it is difficult to +recover from the error on a seekable device and impossible on a +non-seekable device. Most new implementations support this behavior. +The behavior required by POSIX.1\(hy2008 is to return the number of bytes +transferred. +.P +POSIX.1\(hy2008 does not specify when an implementation that buffers +\fIread\fR()s +actually moves the data into the user-supplied buffer, so an +implementation may choose to do this at the latest possible moment. +Therefore, an interrupt arriving earlier may not cause +\fIread\fR() +to return a partial byte count, but rather to return \-1 and set +.IR errno +to +.BR [EINTR] . +.P +Consideration was also given to combining the two previous options, and +setting +.IR errno +to +.BR [EINTR] +while returning a short count. However, not only is there no existing +practice that implements this, it is also contradictory to the idea +that when +.IR errno +is set, the function responsible shall return \-1. +.P +This volume of POSIX.1\(hy2017 intentionally does not specify any +\fIpread\fR() +errors related to pipes, FIFOs, and sockets other than +.BR [ESPIPE] . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIioctl\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIreadv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/readdir.3p b/upstream/archlinux/man3p/readdir.3p new file mode 100644 index 00000000..98f5f3d7 --- /dev/null +++ b/upstream/archlinux/man3p/readdir.3p @@ -0,0 +1,377 @@ +'\" et +.TH READDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +readdir, +readdir_r +\(em read a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +struct dirent *readdir(DIR *\fIdirp\fP); +int readdir_r(DIR *restrict \fIdirp\fP, struct dirent *restrict \fIentry\fP, + struct dirent **restrict \fIresult\fP); +.fi +.SH DESCRIPTION +The type +.BR DIR , +which is defined in the +.IR +header, represents a +.IR "directory stream" , +which is an ordered sequence of all the directory entries in a +particular directory. Directory entries represent files; files may be +removed from a directory or added to a directory asynchronously to the +operation of +\fIreaddir\fR(). +.P +The +\fIreaddir\fR() +function shall return a pointer to a structure representing the +directory entry at the current position in the directory stream +specified by the argument +.IR dirp , +and position the directory stream at the next entry. It shall return a +null pointer upon reaching the end of the directory stream. The +structure +.BR dirent +defined in the +.IR +header describes a directory entry. The value of the structure's +.IR d_ino +member shall be set to the file serial number of the file named by the +.IR d_name +member. If the +.IR d_name +member names a symbolic link, the value of the +.IR d_ino +member shall be set to the file serial number of the symbolic link itself. +.P +The +\fIreaddir\fR() +function shall not return directory entries containing empty names. If +entries for dot or dot-dot exist, one entry shall be returned for dot +and one entry shall be returned for dot-dot; otherwise, they shall not +be returned. +.P +The application shall not modify the structure to which the return +value of +\fIreaddir\fR() +points, nor any storage areas pointed to by pointers within the +structure. The returned pointer, and pointers within the structure, +might be invalidated or the structure or the storage areas might be +overwritten by a subsequent call to +\fIreaddir\fR() +on the same directory stream. They shall not be affected by a call to +\fIreaddir\fR() +on a different directory stream. The returned pointer, and pointers +within the structure, might also be invalidated if the calling thread +is terminated. +.P +If a file is removed from or added to the directory after the most +recent call to +\fIopendir\fR() +or +\fIrewinddir\fR(), +whether a subsequent call to +\fIreaddir\fR() +returns an entry for that file is unspecified. +.P +The +\fIreaddir\fR() +function may buffer several directory entries per actual read +operation; +\fIreaddir\fR() +shall mark for update the last data access timestamp +of the directory each time the directory is actually read. +.P +After a call to +\fIfork\fR(), +either the parent or child (but not both) may continue processing the +directory stream using +\fIreaddir\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(). +If both the parent and child processes use these functions, the result +is undefined. +.P +The +\fIreaddir\fR() +function need not be thread-safe. +.P +Applications wishing to check for error situations should set +.IR errno +to 0 before calling +\fIreaddir\fR(). +If +.IR errno +is set to non-zero on return, an error occurred. +.P +The +\fIreaddir_r\fR() +function shall initialize the +.BR dirent +structure referenced by +.IR entry +to represent the directory entry at the current position in the +directory stream referred to by +.IR dirp , +store a pointer to this structure at the location referenced by +.IR result , +and position the directory stream at the next entry. +.P +The storage pointed to by +.IR entry +shall be large enough for a +.BR dirent +with an array of +.BR char +.IR d_name +members containing at least +{NAME_MAX}+1 +elements. +.P +Upon successful return, the pointer returned at *\fIresult\fP shall have +the same value as the argument +.IR entry . +Upon reaching the end of the directory stream, this pointer shall +have the value NULL. +.P +The +\fIreaddir_r\fR() +function shall not return directory entries containing empty names. +.P +If a file is removed from or added to the directory after the most +recent call to +\fIopendir\fR() +or +\fIrewinddir\fR(), +whether a subsequent call to +\fIreaddir_r\fR() +returns an entry for that file is unspecified. +.P +The +\fIreaddir_r\fR() +function may buffer several directory entries per actual read +operation; +\fIreaddir_r\fR() +shall mark for update the last data access timestamp of the directory +each time the directory is actually read. +.SH "RETURN VALUE" +Upon successful completion, +\fIreaddir\fR() +shall return a pointer to an object of type +.BR "struct dirent" . +When an error is encountered, a null pointer shall be returned and +.IR errno +shall be set to indicate the error. When the end of the directory is +encountered, a null pointer shall be returned and +.IR errno +is not changed. +.P +If successful, the +\fIreaddir_r\fR() +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EOVERFLOW +One of the values in the structure to be returned cannot be represented +correctly. +.P +These functions may fail if: +.TP +.BR EBADF +The +.IR dirp +argument does not refer to an open directory stream. +.TP +.BR ENOENT +The current position of the directory stream is invalid. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following sample program searches the current directory for +each of the arguments supplied on the command line. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +.P +static void lookup(const char *arg) +{ + DIR *dirp; + struct dirent *dp; +.P + if ((dirp = opendir(".")) == NULL) { + perror("couldn\(aqt open \(aq.\(aq"); + return; + } +.P + do { + errno = 0; + if ((dp = readdir(dirp)) != NULL) { + if (strcmp(dp->d_name, arg) != 0) + continue; +.P + (void) printf("found %s\en", arg); + (void) closedir(dirp); + return; +.P + } + } while (dp != NULL); +.P + if (errno != 0) + perror("error reading directory"); + else + (void) printf("failed to find %s\en", arg); + (void) closedir(dirp); + return; +} +.P +int main(int argc, char *argv[]) +{ + int i; + for (i = 1; i < argc; i++) + lookup(argv[i]); + return (0); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIreaddir\fR() +function should be used in conjunction with +\fIopendir\fR(), +\fIclosedir\fR(), +and +\fIrewinddir\fR() +to examine the contents of the directory. +.P +The +\fIreaddir_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.SH RATIONALE +The returned value of +\fIreaddir\fR() +merely \fIrepresents\fP a directory entry. No equivalence should be +inferred. +.P +Historical implementations of +\fIreaddir\fR() +obtain multiple directory entries on a single read operation, which +permits subsequent +\fIreaddir\fR() +operations to operate from the buffered information. Any wording that +required each successful +\fIreaddir\fR() +operation to mark the directory last data access timestamp +for update would disallow such historical performance-oriented +implementations. +.P +When returning a directory entry for the root of a mounted file system, +some historical implementations of +\fIreaddir\fR() +returned the file serial number of the underlying mount point, rather +than of the root of the mounted file system. This behavior is considered +to be a bug, since the underlying file serial number has no significance +to applications. +.P +Since +\fIreaddir\fR() +returns NULL +when it detects an error and when the end of the directory is +encountered, an application that needs to tell the difference must set +.IR errno +to zero before the call and check it if NULL is returned. +Since the function must not change +.IR errno +in the second case and must set it to a non-zero value in the first +case, a zero +.IR errno +after a call returning NULL indicates end-of-directory; otherwise, an +error. +.P +Routines to deal with this problem more directly were proposed: +.sp +.RS 4 +.nf + +int derror (\fIdirp\fP) +DIR *\fIdirp\fP; +.P +void clearderr (\fIdirp\fP) +DIR *\fIdirp\fP; +.fi +.P +.RE +.P +The first would indicate whether an error had occurred, and the second +would clear the error indication. The simpler method involving +.IR errno +was adopted instead by requiring that +\fIreaddir\fR() +not change +.IR errno +when end-of-directory is encountered. +.P +An error or signal indicating that a directory has changed while open +was considered but rejected. +.P +The thread-safe version of the directory reading function returns +values in a user-supplied buffer instead of possibly using a static +data area that may be overwritten by each call. Either the +{NAME_MAX} +compile-time constant or the corresponding +\fIpathconf\fR() +option can be used to determine the maximum sizes of returned +pathnames. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIdirfd\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIrewinddir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/readlink.3p b/upstream/archlinux/man3p/readlink.3p new file mode 100644 index 00000000..18b01c2e --- /dev/null +++ b/upstream/archlinux/man3p/readlink.3p @@ -0,0 +1,262 @@ +'\" et +.TH READLINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +readlink, readlinkat +\(em read the contents of a symbolic link +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t readlink(const char *restrict \fIpath\fP, char *restrict \fIbuf\fP, + size_t \fIbufsize\fP); +.P +#include +.P +ssize_t readlinkat(int \fIfd\fP, const char *restrict \fIpath\fP, + char *restrict \fIbuf\fP, size_t \fIbufsize\fP); +.fi +.SH DESCRIPTION +The +\fIreadlink\fR() +function shall place the contents of the symbolic link referred to by +.IR path +in the buffer +.IR buf +which has size +.IR bufsize . +If the number of bytes in the symbolic link is less than +.IR bufsize , +the contents of the remainder of +.IR buf +are unspecified. If the +.IR buf +argument is not large enough to contain the link content, the first +.IR bufsize +bytes shall be placed in +.IR buf . +.P +If the value of +.IR bufsize +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +Upon successful completion, +\fIreadlink\fR() +shall mark for update the last data access timestamp of the symbolic +link. +.P +The +\fIreadlinkat\fR() +function shall be equivalent to the +\fIreadlink\fR() +function except in the case where +.IR path +specifies a relative path. In this case the symbolic link whose content +is read is relative to the directory associated with the file +descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +If +\fIreadlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIreadlink\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the count of +bytes placed in the buffer. Otherwise, these functions shall return a +value of \-1, leave the buffer unchanged, and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix of +.IR path . +.TP +.BR EINVAL +The +.IR path +argument names a file that is not a symbolic link. +.TP +.BR EIO +An I/O error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIreadlinkat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading the Name of a Symbolic Link" +.P +The following example shows how to read the name of a symbolic link +named +.BR /modules/pass1 . +.sp +.RS 4 +.nf + +#include +.P +char buf[1024]; +ssize_t len; +\&... +if ((len = readlink("/modules/pass1", buf, sizeof(buf)-1)) != -1) + buf[len] = \(aq\e0\(aq; +.fi +.P +.RE +.SH "APPLICATION USAGE" +Conforming applications should not assume that the returned contents of +the symbolic link are null-terminated. +.SH RATIONALE +The type associated with +.IR bufsiz +is a +.BR size_t +in order to be consistent with both the ISO\ C standard and the definition of +\fIread\fR(). +The behavior specified for +\fIreadlink\fR() +when +.IR bufsiz +is zero represents historical practice. For this case, the standard +developers considered a change whereby +\fIreadlink\fR() +would return the number of non-null bytes contained in the symbolic +link with the buffer +.IR buf +remaining unchanged; however, since the +.BR stat +structure member +.IR st_size +value can be used to determine the size of buffer necessary to contain +the contents of the symbolic link as returned by +\fIreadlink\fR(), +this proposal was rejected, and the historical practice retained. +.P +The purpose of the +\fIreadlinkat\fR() +function is to read the content of symbolic links in directories other +than the current working directory without exposure to race conditions. +Any part of the path of a file could be changed in parallel to a call +to +\fIreadlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIreadlinkat\fR() +function it can be guaranteed that the symbolic link read is located +relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/readv.3p b/upstream/archlinux/man3p/readv.3p new file mode 100644 index 00000000..3bc59362 --- /dev/null +++ b/upstream/archlinux/man3p/readv.3p @@ -0,0 +1,152 @@ +'\" et +.TH READV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +readv +\(em read a vector +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t readv(int \fIfildes\fP, const struct iovec *\fIiov\fP, int \fIiovcnt\fP); +.fi +.SH DESCRIPTION +The +\fIreadv\fR() +function shall be equivalent to +\fIread\fR(), +except as described below. The +\fIreadv\fR() +function shall place the input data into the +.IR iovcnt +buffers specified by the members of the +.IR iov +array: +.IR iov [0], +.IR iov [1], +\&.\|.\|., +.IR iov [\c +.IR iovcnt \-1]. +The +.IR iovcnt +argument is valid if greater than 0 and less than or equal to +{IOV_MAX}. +.P +Each +.IR iovec +entry specifies the base address and length of an area +in memory where data should be placed. The +\fIreadv\fR() +function shall always fill an area completely before proceeding +to the next. +.P +Upon successful completion, +\fIreadv\fR() +shall mark for update the last data access timestamp of the file. +.SH "RETURN VALUE" +Refer to +.IR "\fIread\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIread\fR\^(\|)". +.P +In addition, the +\fIreadv\fR() +function shall fail if: +.TP +.BR EINVAL +The sum of the +.IR iov_len +values in the +.IR iov +array overflowed an +.BR ssize_t . +.P +The +\fIreadv\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR iovcnt +argument was less than or equal to 0, or greater than +{IOV_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Reading Data into an Array" +.P +The following example reads data from the file associated with the file +descriptor +.IR fd +into the buffers specified by members of the +.IR iov +array. +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +ssize_t bytes_read; +int fd; +char buf0[20]; +char buf1[30]; +char buf2[40]; +int iovcnt; +struct iovec iov[3]; +.P +iov[0].iov_base = buf0; +iov[0].iov_len = sizeof(buf0); +iov[1].iov_base = buf1; +iov[1].iov_len = sizeof(buf1); +iov[2].iov_base = buf2; +iov[2].iov_len = sizeof(buf2); +\&... +iovcnt = sizeof(iov) / sizeof(struct iovec); +.P +bytes_read = readv(fd, iov, iovcnt); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIread\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIread\fR\^(\|)", +.IR "\fIwritev\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/realloc.3p b/upstream/archlinux/man3p/realloc.3p new file mode 100644 index 00000000..62ff6c54 --- /dev/null +++ b/upstream/archlinux/man3p/realloc.3p @@ -0,0 +1,179 @@ +'\" et +.TH REALLOC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +realloc +\(em memory reallocator +.SH SYNOPSIS +.LP +.nf +#include +.P +void *realloc(void *\fIptr\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIrealloc\fR() +function shall deallocate the old object pointed to by +.IR ptr +and return a pointer to a new object that has the size specified by +.IR size . +The contents of the new object shall be the same as that of the old +object prior to deallocation, up to the lesser of the new and old +sizes. Any bytes in the new object beyond the size of the old object +have indeterminate values. If the size of the space requested is zero, +the behavior shall be implementation-defined: either a null pointer is +returned, or the behavior shall be as if the size were some non-zero +value, except that the behavior is undefined if the returned pointer +is used to access an object. If the space cannot be allocated, +the object shall remain unchanged. +.P +If +.IR ptr +is a null pointer, +\fIrealloc\fR() +shall be equivalent to +\fImalloc\fR() +for the specified size. +.P +If +.IR ptr +does not match a pointer returned earlier by +\fIcalloc\fR(), +\fImalloc\fR(), +or +\fIrealloc\fR() +or if the space has previously been deallocated by a call to +\fIfree\fR() +or +\fIrealloc\fR(), +the behavior is undefined. +.P +The order and contiguity of storage allocated by successive calls to +\fIrealloc\fR() +is unspecified. The pointer returned if the allocation succeeds shall +be suitably aligned so that it may be assigned to a pointer to any type +of object and then used to access such an object in the space allocated +(until the space is explicitly freed or reallocated). Each such +allocation shall yield a pointer to an object disjoint from any other +object. The pointer returned shall point to the start (lowest byte +address) of the allocated space. If the space cannot be allocated, a +null pointer shall be returned. +.SH "RETURN VALUE" +Upon successful completion, +\fIrealloc\fR() +shall return a pointer to the (possibly moved) allocated space. If +.IR size +is 0, either: +.IP " *" 4 +A null pointer shall be returned +and, if +.IR ptr +is not a null pointer, +.IR errno +shall be set to an implementation-defined value. +.IP " *" 4 +A pointer to the allocated space shall be returned, and the +memory object pointed to by +.IR ptr +shall be freed. The application shall ensure that the pointer is not +used to access an object. +.P +If there is not enough available memory, +\fIrealloc\fR() +shall return a null pointer +and set +.IR errno +to +.BR [ENOMEM] . +If +\fIrealloc\fR() +returns a null pointer +and +.IR errno +has been set to +.BR [ENOMEM] , +the memory referenced by +.IR ptr +shall not be changed. +.SH ERRORS +The +\fIrealloc\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient memory is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The description of +\fIrealloc\fR() +has been modified from previous versions of this standard to align +with the ISO/IEC\ 9899:\|1999 standard. Previous versions explicitly permitted a call to +.IR realloc \c +(\fIp\fI, 0) to free the space pointed to by +.IR p +and return a null pointer. While this behavior could be interpreted as +permitted by this version of the standard, the C language committee have +indicated that this interpretation is incorrect. Applications should +assume that if +\fIrealloc\fR() +returns a null pointer, the space pointed to by +.IR p +has not been freed. Since this could lead to double-frees, implementations +should also set +.IR errno +if a null pointer actually indicates a failure, and applications should +only free the space if +.IR errno +was changed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +This standard defers to the ISO\ C standard. While that standard currently has +language that might permit +.IR realloc \c +(\fIp\fI, 0), where +.IR p +is not a null pointer, to free +.IR p +while still returning a null pointer, the committee responsible for that +standard is considering clarifying the language to explicitly prohibit +that alternative. +.SH "SEE ALSO" +.IR "\fIcalloc\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fImalloc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/realpath.3p b/upstream/archlinux/man3p/realpath.3p new file mode 100644 index 00000000..9ea7b541 --- /dev/null +++ b/upstream/archlinux/man3p/realpath.3p @@ -0,0 +1,256 @@ +'\" et +.TH REALPATH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +realpath +\(em resolve a pathname +.SH SYNOPSIS +.LP +.nf +#include +.P +char *realpath(const char *restrict \fIfile_name\fP, + char *restrict \fIresolved_name\fP); +.fi +.SH DESCRIPTION +The +\fIrealpath\fR() +function shall derive, from the pathname pointed to by +.IR file_name , +an absolute pathname that resolves to the same directory entry, whose +resolution does not involve +.BR '.' , +.BR '..' , +or symbolic links. If +.IR resolved_name +is a null pointer, the generated pathname shall be stored as a +null-terminated string in a buffer allocated as if by a call to +\fImalloc\fR(). +Otherwise, if +{PATH_MAX} +is defined as a constant in the +.IR +header, then the generated pathname shall be stored as a null-terminated +string, up to a maximum of +{PATH_MAX} +bytes, in the buffer pointed to by +.IR resolved_name . +.P +If +.IR resolved_name +is not a null pointer and +{PATH_MAX} +is not defined as a constant in the +.IR +header, the behavior is undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIrealpath\fR() +shall return a pointer to the buffer containing the resolved name. +Otherwise, +\fIrealpath\fR() +shall return a null pointer and set +.IR errno +to indicate the error. +.P +If the +.IR resolved_name +argument is a null pointer, the pointer returned by +\fIrealpath\fR() +can be passed to +\fIfree\fR(). +.P +If the +.IR resolved_name +argument is not a null pointer and the +\fIrealpath\fR() +function fails, the contents of the buffer pointed to by +.IR resolved_name +are undefined. +.SH ERRORS +The +\fIrealpath\fR() +function shall fail if: +.TP +.BR EACCES +Search permission was denied for a component of the path prefix of +.IR file_name . +.TP +.BR EINVAL +The +.IR file_name +argument is a null pointer. +.TP +.BR EIO +An error occurred while reading from the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR file_name +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR file_name +does not name an existing file or +.IR file_name +points to an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR file_name +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIrealpath\fR() +function may fail if: +.TP +.BR EACCES +The +.IR file_name +argument does not begin with a + +and none of the symbolic links (if any) processed during pathname +resolution of +.IR file_name +had contents that began with a +, +and either search permission was denied for the current directory or +read or search permission was denied for a directory above the current +directory in the file hierarchy. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR file_name +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating an Absolute Pathname" +.P +The following example generates an absolute pathname for the file +identified by the +.IR symlinkpath +argument. The generated pathname is stored in the buffer pointed to by +.IR actualpath . +.sp +.RS 4 +.nf + +#include +\&... +char *symlinkpath = "/tmp/symlink/file"; +char *actualpath; +.P +actualpath = realpath(symlinkpath, NULL); +if (actualpath != NULL) +{ + ... use actualpath ... +.P + free(actualpath); +} +else +{ + ... handle error ... +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIrealpath\fR(), +this is the return value. +.SH RATIONALE +Since +\fIrealpath\fR() +has no +.IR length +argument, if +{PATH_MAX} +is not defined as a constant in +.IR , +applications have no way of determining how large a buffer they need +to allocate for it to be safe to pass to +\fIrealpath\fR(). +A +{PATH_MAX} +value obtained from a prior +\fIpathconf\fR() +call is out-of-date by the time +\fIrealpath\fR() +is called. Hence the only reliable way to use +\fIrealpath\fR() +when +{PATH_MAX} +is not defined in +.IR +is to pass a null pointer for +.IR resolved_name +so that +\fIrealpath\fR() +will allocate a buffer of the necessary size. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpathconf\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fIgetcwd\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/recv.3p b/upstream/archlinux/man3p/recv.3p new file mode 100644 index 00000000..e55d2a05 --- /dev/null +++ b/upstream/archlinux/man3p/recv.3p @@ -0,0 +1,222 @@ +'\" et +.TH RECV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +recv +\(em receive a message from a connected socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t recv(int \fIsocket\fP, void *\fIbuffer\fP, size_t \fIlength\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIrecv\fR() +function shall receive a message from a connection-mode or +connectionless-mode socket. It is normally used with connected sockets +because it does not permit the application to retrieve the source +address of received data. +.P +The +\fIrecv\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 10 +Specifies the socket file descriptor. +.IP "\fIbuffer\fR" 10 +Points to a buffer where the message should be stored. +.IP "\fIlength\fR" 10 +Specifies the length in bytes of the buffer pointed to by the +.IR buffer +argument. +.IP "\fIflags\fR" 10 +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following values: +.RS 10 +.IP MSG_PEEK 12 +Peeks at an incoming message. The data is treated as unread and the +next +\fIrecv\fR() +or similar function shall still return this data. +.IP MSG_OOB 12 +Requests out-of-band data. The significance and semantics of +out-of-band data are protocol-specific. +.IP MSG_WAITALL 12 +On SOCK_STREAM sockets this requests that the function block until the +full amount of data can be returned. The function may return the +smaller amount of data if the socket is a message-based socket, if a +signal is caught, if the connection is terminated, if MSG_PEEK was +specified, or if an error is pending for the socket. +.RE +.P +The +\fIrecv\fR() +function shall return the length of the message written to the buffer +pointed to by the +.IR buffer +argument. For message-based sockets, such as SOCK_DGRAM and +SOCK_SEQPACKET, the entire message shall be read in a single operation. +If a message is too long to fit in the supplied buffer, and MSG_PEEK is +not set in the +.IR flags +argument, the excess bytes shall be discarded. For stream-based +sockets, such as SOCK_STREAM, message boundaries shall be ignored. In +this case, data shall be returned to the user as soon as it becomes +available, and no data shall be discarded. +.P +If the MSG_WAITALL flag is not set, data shall be returned only up to +the end of the first message. +.P +If no messages are available at the socket and O_NONBLOCK is not set on +the socket's file descriptor, +\fIrecv\fR() +shall block until a message arrives. If no messages are available at +the socket and O_NONBLOCK is set on the socket's file descriptor, +\fIrecv\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.SH "RETURN VALUE" +Upon successful completion, +\fIrecv\fR() +shall return the length of the message in bytes. If no messages are +available to be received and the peer has performed an orderly +shutdown, +\fIrecv\fR() +shall return 0. Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIrecv\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and no data is +waiting to be received; or MSG_OOB is set and no out-of-band data is +available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await out-of-band data. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +The +\fIrecv\fR() +function was interrupted by a signal that was caught, before any data +was available. +.TP +.BR EINVAL +The MSG_OOB flag is set and no out-of-band data is available. +.TP +.BR ENOTCONN +A receive is attempted on a connection-mode socket that is not +connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The specified flags are not supported for this socket type or +protocol. +.TP +.BR ETIMEDOUT +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.P +The +\fIrecv\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIrecv\fR() +function is equivalent to +\fIrecvfrom\fR() +with null pointer +.IR address +and +.IR address_len +arguments, and to +\fIread\fR() +if the +.IR socket +argument refers to a socket and the +.IR flags +argument is 0. +.P +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when data is available to be +received. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/recvfrom.3p b/upstream/archlinux/man3p/recvfrom.3p new file mode 100644 index 00000000..3e427a72 --- /dev/null +++ b/upstream/archlinux/man3p/recvfrom.3p @@ -0,0 +1,245 @@ +'\" et +.TH RECVFROM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +recvfrom +\(em receive a message from a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t recvfrom(int \fIsocket\fP, void *restrict \fIbuffer\fP, size_t \fIlength\fP, + int \fIflags\fP, struct sockaddr *restrict \fIaddress\fP, + socklen_t *restrict \fIaddress_len\fP); +.fi +.SH DESCRIPTION +The +\fIrecvfrom\fR() +function shall receive a message from a connection-mode or +connectionless-mode socket. It is normally used with +connectionless-mode sockets because it permits the application to +retrieve the source address of received data. +.P +The +\fIrecvfrom\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fIbuffer\fR" 12 +Points to the buffer where the message should be stored. +.IP "\fIlength\fR" 12 +Specifies the length in bytes of the buffer pointed to by the +.IR buffer +argument. +.IP "\fIflags\fR" 12 +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following values: +.RS 12 +.IP MSG_PEEK 12 +Peeks at an incoming message. The data is treated as unread and the +next +\fIrecvfrom\fR() +or similar function shall still return this data. +.IP MSG_OOB 12 +Requests out-of-band data. The significance and semantics of +out-of-band data are protocol-specific. +.IP MSG_WAITALL 12 +On SOCK_STREAM sockets this requests that the function block until the +full amount of data can be returned. The function may return the +smaller amount of data if the socket is a message-based socket, if a +signal is caught, if the connection is terminated, if MSG_PEEK was +specified, or if an error is pending for the socket. +.RE +.IP "\fIaddress\fR" 12 +A null pointer, or points to a +.BR sockaddr +structure in which the sending address is to be stored. The length and +format of the address depend on the address family of the socket. +.IP "\fIaddress_len\fR" 12 +Either a null pointer, if +.IR address +is a null pointer, or a pointer to a +.BR socklen_t +object which on input specifies the length of the supplied +.BR sockaddr +structure, and on output specifies the length of the stored address. +.P +The +\fIrecvfrom\fR() +function shall return the length of the message written to the buffer +pointed to by the +.IR buffer +argument. For message-based sockets, such as +SOCK_RAW, +SOCK_DGRAM, and SOCK_SEQPACKET, the entire message shall be read in a +single operation. If a message is too long to fit in the supplied +buffer, and MSG_PEEK is not set in the +.IR flags +argument, the excess bytes shall be discarded. For stream-based +sockets, such as SOCK_STREAM, message boundaries shall be ignored. In +this case, data shall be returned to the user as soon as it becomes +available, and no data shall be discarded. +.P +If the MSG_WAITALL flag is not set, data shall be returned only up to +the end of the first message. +.P +Not all protocols provide the source address for messages. If the +.IR address +argument is not a null pointer and the protocol provides the source +address of messages, the source address of the received message shall +be stored in the +.BR sockaddr +structure pointed to by the +.IR address +argument, and the length of this address shall be stored in the object +pointed to by the +.IR address_len +argument. +.P +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. +.P +If the +.IR address +argument is not a null pointer and the protocol does not provide the +source address of messages, the value stored in the object pointed to +by +.IR address +is unspecified. +.P +If no messages are available at the socket and O_NONBLOCK is not set on +the socket's file descriptor, +\fIrecvfrom\fR() +shall block until a message arrives. If no messages are available at +the socket and O_NONBLOCK is set on the socket's file descriptor, +\fIrecvfrom\fR() +shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.SH "RETURN VALUE" +Upon successful completion, +\fIrecvfrom\fR() +shall return the length of the message in bytes. If no messages are +available to be received and the peer has performed an orderly +shutdown, +\fIrecvfrom\fR() +shall return 0. Otherwise, the function shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIrecvfrom\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and no data is +waiting to be received; or MSG_OOB is set and no out-of-band data is +available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await out-of-band data. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +A signal interrupted +\fIrecvfrom\fR() +before any data was available. +.TP +.BR EINVAL +The MSG_OOB flag is set and no out-of-band data is available. +.TP +.BR ENOTCONN +A receive is attempted on a connection-mode socket that is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The specified flags are not supported for this socket type. +.TP +.BR ETIMEDOUT +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.P +The +\fIrecvfrom\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when data is available to be +received. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/recvmsg.3p b/upstream/archlinux/man3p/recvmsg.3p new file mode 100644 index 00000000..2bfb18db --- /dev/null +++ b/upstream/archlinux/man3p/recvmsg.3p @@ -0,0 +1,280 @@ +'\" et +.TH RECVMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +recvmsg +\(em receive a message from a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t recvmsg(int \fIsocket\fP, struct msghdr *\fImessage\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIrecvmsg\fR() +function shall receive a message from a connection-mode or +connectionless-mode socket. It is normally used with +connectionless-mode sockets because it permits the application to +retrieve the source address of received data. +.P +The +\fIrecvmsg\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fImessage\fR" 12 +Points to a +.BR msghdr +structure, containing both the buffer to store the source address and +the buffers for the incoming message. The length and format of the +address depend on the address family of the socket. The +.IR msg_flags +member is ignored on input, but may contain meaningful values on +output. +.IP "\fIflags\fR" 12 +Specifies the type of message reception. Values of this argument are +formed by logically OR'ing zero or more of the following values: +.RS 12 +.IP MSG_OOB 12 +Requests out-of-band data. The significance and semantics of +out-of-band data are protocol-specific. +.IP MSG_PEEK 12 +Peeks at the incoming message. +.IP MSG_WAITALL 12 +On SOCK_STREAM sockets this requests that the function block until the +full amount of data can be returned. The function may return the +smaller amount of data if the socket is a message-based socket, if a +signal is caught, if the connection is terminated, if MSG_PEEK was +specified, or if an error is pending for the socket. +.RE +.P +The +\fIrecvmsg\fR() +function shall receive messages from unconnected or connected +sockets and shall return the length of the message. +.P +The +\fIrecvmsg\fR() +function shall return the total length of the message. For +message-based sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, the +entire message shall be read in a single operation. If a message is too +long to fit in the supplied buffers, and MSG_PEEK is not set in the +.IR flags +argument, the excess bytes shall be discarded, and MSG_TRUNC shall be +set in the +.IR msg_flags +member of the +.BR msghdr +structure. For stream-based sockets, such as SOCK_STREAM, message +boundaries shall be ignored. In this case, data shall be returned to +the user as soon as it becomes available, and no data shall be +discarded. +.P +If the MSG_WAITALL flag is not set, data shall be returned only up to +the end of the first message. +.P +If no messages are available at the socket and O_NONBLOCK is not set on +the socket's file descriptor, +\fIrecvmsg\fR() +shall block until a message arrives. If no messages are available at +the socket and O_NONBLOCK is set on the socket's file descriptor, the +\fIrecvmsg\fR() +function shall fail and set +.IR errno +to +.BR [EAGAIN] +or +.BR [EWOULDBLOCK] . +.P +In the +.BR msghdr +structure, the +.IR msg_name +member may be a null pointer if the source address is not required. +Otherwise, if the socket is unconnected, the +.IR msg_name +member points to a +.BR sockaddr +structure in which the source address is to be stored, and the +.IR msg_namelen +member on input specifies the length of the supplied +.BR sockaddr +structure and on output specifies the length of the stored address. +If the actual length of the address is greater than the length of the +supplied +.BR sockaddr +structure, the stored address shall be truncated. If the socket is +connected, the +.IR msg_name +and +.IR msg_namelen +members shall be ignored. The +.IR msg_iov +and +.IR msg_iovlen +fields are used to specify where the received data shall be stored. +The +.IR msg_iov +member points to an array of +.BR iovec +structures; the +.IR msg_iovlen +member shall be set to the dimension of this array. In each +.BR iovec +structure, the +.IR iov_base +field specifies a storage area and the +.IR iov_len +field gives its size in bytes. Each storage area indicated by +.IR msg_iov +is filled with received data in turn until all of the received data is +stored or all of the areas have been filled. +.P +Upon successful completion, the +.IR msg_flags +member of the message header shall be the bitwise-inclusive OR of all +of the following flags that indicate conditions detected for the +received message: +.IP MSG_EOR 12 +End-of-record was received (if supported by the protocol). +.IP MSG_OOB 12 +Out-of-band data was received. +.IP MSG_TRUNC 12 +Normal data was truncated. +.IP MSG_CTRUNC 12 +Control data was truncated. +.SH "RETURN VALUE" +Upon successful completion, +\fIrecvmsg\fR() +shall return the length of the message in bytes. If no messages are +available to be received and the peer has performed an orderly +shutdown, +\fIrecvmsg\fR() +shall return 0. Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIrecvmsg\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and no data is +waiting to be received; or MSG_OOB is set and no out-of-band data is +available and either the socket's file descriptor is marked O_NONBLOCK +or the socket does not support blocking to await out-of-band data. +.TP +.BR EBADF +The +.IR socket +argument is not a valid open file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +This function was interrupted by a signal before any data was +available. +.TP +.BR EINVAL +The sum of the +.IR iov_len +values overflows a +.BR ssize_t , +or the MSG_OOB flag is set and no out-of-band data is available. +.TP +.BR EMSGSIZE +The +.IR msg_iovlen +member of the +.BR msghdr +structure pointed to by +.IR message +is less than or equal to 0, or is greater than +{IOV_MAX}. +.TP +.BR ENOTCONN +A receive is attempted on a connection-mode socket that is not +connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The specified flags are not supported for this socket type. +.TP +.BR ETIMEDOUT +The connection timed out during connection establishment, or due to a +transmission timeout on active connection. +.P +The +\fIrecvmsg\fR() +function may fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when data is available to be +received. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/regcomp.3p b/upstream/archlinux/man3p/regcomp.3p new file mode 100644 index 00000000..91a30632 --- /dev/null +++ b/upstream/archlinux/man3p/regcomp.3p @@ -0,0 +1,875 @@ +'\" et +.TH REGCOMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +regcomp, +regerror, +regexec, +regfree +\(em regular expression matching +.SH SYNOPSIS +.LP +.nf +#include +.P +int regcomp(regex_t *restrict \fIpreg\fP, const char *restrict \fIpattern\fP, + int \fIcflags\fP); +size_t regerror(int \fIerrcode\fP, const regex_t *restrict \fIpreg\fP, + char *restrict \fIerrbuf\fP, size_t \fIerrbuf_size\fP); +int regexec(const regex_t *restrict \fIpreg\fP, const char *restrict \fIstring\fP, + size_t \fInmatch\fP, regmatch_t \fIpmatch\fP[restrict], int \fIeflags\fP); +void regfree(regex_t *\fIpreg\fP); +.fi +.SH DESCRIPTION +These functions interpret +.IR basic +and +.IR extended +regular expressions as described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 9" ", " "Regular Expressions". +.P +The +.BR regex_t +structure is defined in +.IR +and contains at least the following member: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +size_t!re_nsub!T{ +Number of parenthesized subexpressions. +T} +.TE +.P +The +.BR regmatch_t +structure is defined in +.IR +and contains at least the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +regoff_t!rm_so!T{ +Byte offset from start of \fIstring\fP to start of substring. +T} +regoff_t!rm_eo!T{ +Byte offset from start of +.IR string +of the first character after the end of substring. +T} +.TE +.P +The +\fIregcomp\fR() +function shall compile the regular expression contained in the string +pointed to by the +.IR pattern +argument and place the results in the structure pointed to by +.IR preg . +The +.IR cflags +argument is the bitwise-inclusive OR of zero or more of the following +flags, which are defined in the +.IR +header: +.IP REG_EXTENDED 14 +Use Extended Regular Expressions. +.IP REG_ICASE 14 +Ignore case in match (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 9" ", " "Regular Expressions"). +.IP REG_NOSUB 14 +Report only success/fail in +\fIregexec\fR(). +.IP REG_NEWLINE 14 +Change the handling of + +characters, as described in the text. +.P +The default regular expression type for +.IR pattern +is a Basic Regular Expression. The application can specify Extended +Regular Expressions using the REG_EXTENDED +.IR cflags +flag. +.P +If the REG_NOSUB flag was not set in +.IR cflags , +then +\fIregcomp\fR() +shall set +.IR re_nsub +to the number of parenthesized subexpressions (delimited by +.BR \(dq\e(\e)\(dq +in basic regular expressions or +.BR \(dq(\|)\(dq +in extended regular expressions) found in +.IR pattern . +.P +The +\fIregexec\fR() +function compares the null-terminated string specified by +.IR string +with the compiled regular expression +.IR preg +initialized by a previous call to +\fIregcomp\fR(). +If it finds a match, +\fIregexec\fR() +shall return 0; otherwise, it shall return non-zero indicating either +no match or an error. The +.IR eflags +argument is the bitwise-inclusive OR of zero or more of the following +flags, which are defined in the +.IR +header: +.IP REG_NOTBOL 14 +The first character of the string pointed to by +.IR string +is not the beginning of the line. Therefore, the + +character +(\c +.BR '\(ha' ), +when taken as a special character, shall not match the beginning of +.IR string . +.IP REG_NOTEOL 14 +The last character of the string pointed to by +.IR string +is not the end of the line. Therefore, the + +(\c +.BR '$' ), +when taken as a special character, shall not match the end of +.IR string . +.P +If +.IR nmatch +is 0 or REG_NOSUB was set in the +.IR cflags +argument to +\fIregcomp\fR(), +then +\fIregexec\fR() +shall ignore the +.IR pmatch +argument. Otherwise, the application shall ensure that the +.IR pmatch +argument points to an array with at least +.IR nmatch +elements, and +\fIregexec\fR() +shall fill in the elements of that array with offsets of the substrings +of +.IR string +that correspond to the parenthesized subexpressions of +.IR pattern : +.IR pmatch [\c +.IR i ].\c +.IR rm_so +shall be the byte offset of the beginning and +.IR pmatch [\c +.IR i ].\c +.IR rm_eo +shall be one greater than the byte offset of the end of substring +.IR i . +(Subexpression +.IR i +begins at the +.IR i th +matched open parenthesis, counting from 1.) Offsets in +.IR pmatch [0] +identify the substring that corresponds to the entire regular +expression. Unused elements of +.IR pmatch +up to +.IR pmatch [\c +.IR nmatch \-1] +shall be filled with \-1. If there are more than +.IR nmatch +subexpressions in +.IR pattern +(\c +.IR pattern +itself counts as a subexpression), then +\fIregexec\fR() +shall still do the match, but shall record only the first +.IR nmatch +substrings. +.P +When matching a basic or extended regular expression, any given +parenthesized subexpression of +.IR pattern +might participate in the match of several different substrings of +.IR string , +or it might not match any substring even though the pattern as a whole +did match. The following rules shall be used to determine which +substrings to report in +.IR pmatch +when matching regular expressions: +.IP " 1." 4 +If subexpression +.IR i +in a regular expression is not contained within another subexpression, +and it participated in the match several times, then the byte offsets +in +.IR pmatch [\c +.IR i ] +shall delimit the last such match. +.IP " 2." 4 +If subexpression +.IR i +is not contained within another subexpression, and it did not +participate in an otherwise successful match, the byte offsets in +.IR pmatch [\c +.IR i ] +shall be \-1. A subexpression does not participate in the match when: +.sp +.RS +.BR '*' +or +.BR \(dq\e{\e}\(dq +appears immediately after the subexpression in a basic regular +expression, or +.BR '*' , +.BR '?' , +or +.BR \(dq{\|}\(dq +appears immediately after the subexpression in an extended regular +expression, and the subexpression did not match (matched 0 times) +.RE +.RS 4 +.P +or: +.sp +.RS +.BR '|' +is used in an extended regular expression to select this subexpression +or another, and the other subexpression matched. +.RE +.RE +.IP " 3." 4 +If subexpression +.IR i +is contained within another subexpression +.IR j , +and +.IR i +is not contained within any other subexpression that is contained +within +.IR j , +and a match of subexpression +.IR j +is reported in +.IR pmatch [\c +.IR j ], +then the match or non-match of subexpression +.IR i +reported in +.IR pmatch [\c +.IR i ] +shall be as described in 1. and 2. above, but within the substring +reported in +.IR pmatch [\c +.IR j ] +rather than the whole string. The offsets in +.IR pmatch [\c +.IR i ] +are still relative to the start of +.IR string . +.IP " 4." 4 +If subexpression +.IR i +is contained in subexpression +.IR j , +and the byte offsets in +.IR pmatch [\c +.IR j ] +are \-1, then the pointers in +.IR pmatch [\c +.IR i ] +shall also be \-1. +.IP " 5." 4 +If subexpression +.IR i +matched a zero-length string, then both byte offsets in +.IR pmatch [\c +.IR i ] +shall be the byte offset of the character or null terminator +immediately following the zero-length string. +.P +If, when +\fIregexec\fR() +is called, the locale is different from when the regular expression was +compiled, the result is undefined. +.P +If REG_NEWLINE is not set in +.IR cflags , +then a + +in +.IR pattern +or +.IR string +shall be treated as an ordinary character. If REG_NEWLINE is set, then + +shall be treated as an ordinary character except as follows: +.IP " 1." 4 +A + +in +.IR string +shall not be matched by a + +outside a bracket expression or by any form of a non-matching list +(see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 9" ", " "Regular Expressions"). +.IP " 2." 4 +A + +(\c +.BR '\(ha' ) +in +.IR pattern , +when used to specify expression anchoring (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 9.3.8" ", " "BRE Expression Anchoring"), +shall match the zero-length string immediately after a + +in +.IR string , +regardless of the setting of REG_NOTBOL. +.IP " 3." 4 +A + +(\c +.BR '$' ) +in +.IR pattern , +when used to specify expression anchoring, shall match the zero-length +string immediately before a + +in +.IR string , +regardless of the setting of REG_NOTEOL. +.P +The +\fIregfree\fR() +function frees any memory allocated by +\fIregcomp\fR() +associated with +.IR preg . +.P +The following constants are defined as the minimum set of error return +values, although other errors listed as implementation extensions in +.IR +are possible: +.IP REG_BADBR 14 +Content of +.BR \(dq\e{\e}\(dq +invalid: not a number, number too large, more than two numbers, first +larger than second. +.IP REG_BADPAT 14 +Invalid regular expression. +.IP REG_BADRPT 14 +.BR '?' , +.BR '*' , +or +.BR '+' +not preceded by valid regular expression. +.IP REG_EBRACE 14 +.BR \(dq\e{\e}\(dq +imbalance. +.IP REG_EBRACK 14 +.BR \(dq[]\(dq +imbalance. +.IP REG_ECOLLATE 14 +Invalid collating element referenced. +.IP REG_ECTYPE 14 +Invalid character class type referenced. +.IP REG_EESCAPE 14 +Trailing + +character in pattern. +.IP REG_EPAREN 14 +.BR \(dq\e(\e)\(dq +or +.BR \(dq()\(dq +imbalance. +.IP REG_ERANGE 14 +Invalid endpoint in range expression. +.IP REG_ESPACE 14 +Out of memory. +.IP REG_ESUBREG 14 +Number in +.BR \(dq\edigit\(dq +invalid or in error. +.IP REG_NOMATCH 14 +\fIregexec\fR() +failed to match. +.P +If more than one error occurs in processing a function call, any one +of the possible constants may be returned, as the order of detection is +unspecified. +.P +The +\fIregerror\fR() +function provides a mapping from error codes returned by +\fIregcomp\fR() +and +\fIregexec\fR() +to unspecified printable strings. It generates a string corresponding +to the value of the +.IR errcode +argument, which the application shall ensure is the last non-zero value +returned by +\fIregcomp\fR() +or +\fIregexec\fR() +with the given value of +.IR preg . +If +.IR errcode +is not such a value, the content of the generated string is unspecified. +.P +If +.IR preg +is a null pointer, but +.IR errcode +is a value returned by a previous call to +\fIregexec\fR() +or +\fIregcomp\fR(), +the +\fIregerror\fR() +still generates an error string corresponding to the value of +.IR errcode , +but it might not be as detailed under some implementations. +.P +If the +.IR errbuf_size +argument is not 0, +\fIregerror\fR() +shall place the generated string into the buffer of size +.IR errbuf_size +bytes pointed to by +.IR errbuf . +If the string (including the terminating null) cannot fit in the +buffer, +\fIregerror\fR() +shall truncate the string and null-terminate the result. +.P +If +.IR errbuf_size +is 0, +\fIregerror\fR() +shall ignore the +.IR errbuf +argument, and return the size of the buffer needed to hold the +generated string. +.P +If the +.IR preg +argument to +\fIregexec\fR() +or +\fIregfree\fR() +is not a compiled regular expression returned by +\fIregcomp\fR(), +the result is undefined. A +.IR preg +is no longer treated as a compiled regular expression after it is given +to +\fIregfree\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fIregcomp\fR() +function shall return 0. Otherwise, it shall return an integer value +indicating an error as described in +.IR , +and the content of +.IR preg +is undefined. If a code is returned, the interpretation shall be as +given in +.IR . +.P +If +\fIregcomp\fR() +detects an invalid RE, it may return REG_BADPAT, or it may return one +of the error codes that more precisely describes the error. +.P +Upon successful completion, the +\fIregexec\fR() +function shall return 0. Otherwise, it shall return REG_NOMATCH to +indicate no match. +.P +Upon successful completion, the +\fIregerror\fR() +function shall return the number of bytes needed to hold the entire +generated string, including the null termination. If the return value +is greater than +.IR errbuf_size , +the string returned in the buffer pointed to by +.IR errbuf +has been truncated. +.P +The +\fIregfree\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +.sp +.RS 4 +.nf + +#include +.P +/* + * Match string against the extended regular expression in + * pattern, treating errors as no match. + * + * Return 1 for match, 0 for no match. + */ +.P +int +match(const char *string, char *pattern) +{ + int status; + regex_t re; +.P + if (regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB) != 0) { + return(0); /* Report error. */ + } + status = regexec(&re, string, (size_t) 0, NULL, 0); + regfree(&re); + if (status != 0) { + return(0); /* Report error. */ + } + return(1); +} +.fi +.P +.RE +.P +The following demonstrates how the REG_NOTBOL flag could be used with +\fIregexec\fR() +to find all substrings in a line that match a pattern supplied by a user. +(For simplicity of the example, very little error checking is done.) +.sp +.RS 4 +.nf + +(void) regcomp (&re, pattern, 0); +/* This call to regexec() finds the first match on the line. */ +error = regexec (&re, &buffer[0], 1, &pm, 0); +while (error == 0) { /* While matches found. */ + /* Substring found between pm.rm_so and pm.rm_eo. */ + /* This call to regexec() finds the next match. */ + error = regexec (&re, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +An application could use: +.sp +.RS 4 +.nf + +regerror(code,preg,(char *)NULL,(size_t)0) +.fi +.P +.RE +.P +to find out how big a buffer is needed for the generated string, +\fImalloc\fR() +a buffer to hold the string, and then call +\fIregerror\fR() +again to get the string. Alternatively, it could allocate a fixed, +static buffer that is big enough to hold most strings, and then use +\fImalloc\fR() +to allocate a larger buffer if it finds that this is too small. +.P +To match a pattern as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13" ", " "Pattern Matching Notation", +use the +\fIfnmatch\fR() +function. +.SH RATIONALE +The +\fIregexec\fR() +function must fill in all +.IR nmatch +elements of +.IR pmatch , +where +.IR nmatch +and +.IR pmatch +are supplied by the application, even if some elements of +.IR pmatch +do not correspond to subexpressions in +.IR pattern . +The application developer should note that there is probably no reason +for using a value of +.IR nmatch +that is larger than +.IR preg \->\c +.IR re_nsub +1. +.P +The REG_NEWLINE flag supports a use of RE matching that is needed in +some applications like text editors. In such applications, the user +supplies an RE asking the application to find a line that matches the +given expression. An anchor in such an RE anchors at the beginning or +end of any line. Such an application can pass a sequence of +-separated +lines to +\fIregexec\fR() +as a single long string and specify REG_NEWLINE to +\fIregcomp\fR() +to get the desired behavior. The application must ensure that there are +no explicit + +characters in +.IR pattern +if it wants to ensure that any match occurs entirely within a single +line. +.P +The REG_NEWLINE flag affects the behavior of +\fIregexec\fR(), +but it is in the +.IR cflags +parameter to +\fIregcomp\fR() +to allow flexibility of implementation. Some implementations will want +to generate the same compiled RE in +\fIregcomp\fR() +regardless of the setting of REG_NEWLINE and have +\fIregexec\fR() +handle anchors differently based on the setting of the flag. Other +implementations will generate different compiled REs based on the +REG_NEWLINE. +.P +The REG_ICASE flag supports the operations taken by the +.IR grep +.BR \-i +option and the historical implementations of +.IR ex +and +.IR vi . +Including this flag will make it easier for application code to be +written that does the same thing as these utilities. +.P +The substrings reported in +.IR pmatch [\|] +are defined using offsets from the start of the string rather than +pointers. This allows type-safe access to both constant and non-constant +strings. +.P +The type +.BR regoff_t +is used for the elements of +.IR pmatch [\|] +to ensure that the application can represent large arrays in memory +(important for an application conforming to the Shell and Utilities volume of POSIX.1\(hy2017). +.P +The 1992 edition of this standard required +.BR regoff_t +to be at least as wide as +.BR off_t , +to facilitate future extensions in which the string to be searched is +taken from a file. However, these future extensions have not appeared. +The requirement rules out popular implementations with 32-bit +.BR regoff_t +and 64-bit +.BR off_t , +so it has been removed. +.P +The standard developers rejected the inclusion of a +\fIregsub\fR() +function that would be used to do substitutions for a matched RE. While +such a routine would be useful to some applications, its utility would +be much more limited than the matching function described here. Both RE +parsing and substitution are possible to implement without support +other than that required by the ISO\ C standard, but matching is much more +complex than substituting. The only difficult part of substitution, +given the information supplied by +\fIregexec\fR(), +is finding the next character in a string when there can be multi-byte +characters. That is a much larger issue, and one that needs a more +general solution. +.P +The +.IR errno +variable has not been used for error returns to avoid filling the +.IR errno +name space for this feature. +.P +The interface is defined so that the matched substrings +.IR rm_sp +and +.IR rm_ep +are in a separate +.BR regmatch_t +structure instead of in +.BR regex_t . +This allows a single compiled RE to be used simultaneously in several +contexts; in +\fImain\fR() +and a signal handler, perhaps, or in multiple threads of lightweight +processes. (The +.IR preg +argument to +\fIregexec\fR() +is declared with type +.BR const , +so the implementation is not permitted to use the structure to store +intermediate results.) It also allows an application to request an +arbitrary number of substrings from an RE. The number of +subexpressions in the RE is reported in +.IR re_nsub +in +.IR preg . +With this change to +\fIregexec\fR(), +consideration was given to dropping the REG_NOSUB flag since the user +can now specify this with a zero +.IR nmatch +argument to +\fIregexec\fR(). +However, keeping REG_NOSUB allows an implementation to use a different +(perhaps more efficient) algorithm if it knows in +\fIregcomp\fR() +that no subexpressions need be reported. The implementation is only +required to fill in +.IR pmatch +if +.IR nmatch +is not zero and if REG_NOSUB is not specified. Note that the +.BR size_t +type, as defined in the ISO\ C standard, is unsigned, so the description of +\fIregexec\fR() +does not need to address negative values of +.IR nmatch . +.P +REG_NOTBOL was added to allow an application to do repeated searches +for the same pattern in a line. If the pattern contains a + +character that should match the beginning of a line, then the pattern +should only match when matched against the beginning of the line. +Without the REG_NOTBOL flag, the application could rewrite the +expression for subsequent matches, but in the general case this would +require parsing the expression. The need for REG_NOTEOL is not as +clear; it was added for symmetry. +.P +The addition of the +\fIregerror\fR() +function addresses the historical need for conforming application +programs to have access to error information more than ``Function +failed to compile/match your RE for unknown reasons''. +.P +This interface provides for two different methods of dealing with error +conditions. The specific error codes (REG_EBRACE, for example), defined +in +.IR , +allow an application to recover from an error if it is so able. Many +applications, especially those that use patterns supplied by a user, +will not try to deal with specific error cases, but will just use +\fIregerror\fR() +to obtain a human-readable error message to present to the user. +.P +The +\fIregerror\fR() +function uses a scheme similar to +\fIconfstr\fR() +to deal with the problem of allocating memory to hold the generated +string. The scheme used by +\fIstrerror\fR() +in the ISO\ C standard was considered unacceptable since it creates difficulties +for multi-threaded applications. +.P +The +.IR preg +argument is provided to +\fIregerror\fR() +to allow an implementation to generate a more descriptive message than +would be possible with +.IR errcode +alone. An implementation might, for example, save the character offset +of the offending character of the pattern in a field of +.IR preg , +and then include that in the generated message string. The +implementation may also ignore +.IR preg . +.P +A REG_FILENAME flag was considered, but omitted. This flag caused +\fIregexec\fR() +to match patterns as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13" ", " "Pattern Matching Notation" +instead of REs. This service is now provided by the +\fIfnmatch\fR() +function. +.P +Notice that there is a difference in philosophy between the ISO\ POSIX\(hy2:\|1993 standard and +POSIX.1\(hy2008 in how to handle a ``bad'' regular expression. The ISO\ POSIX\(hy2:\|1993 standard says +that many bad constructs ``produce undefined results'', or that +``the interpretation is undefined''. POSIX.1\(hy2008, however, says that the +interpretation of such REs is unspecified. The term ``undefined'' means +that the action by the application is an error, of similar severity +to passing a bad pointer to a function. +.P +The +\fIregcomp\fR() +and +\fIregexec\fR() +functions are required to accept any null-terminated string as the +.IR pattern +argument. If the meaning of the string is ``undefined'', the behavior +of the function is ``unspecified''. POSIX.1\(hy2008 does not specify how the +functions will interpret the pattern; they might return error codes, or +they might do pattern matching in some completely unexpected way, but +they should not do something like abort the process. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfnmatch\fR\^(\|)", +.IR "\fIglob\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 9" ", " "Regular Expressions", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.13" ", " "Pattern Matching Notation" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/remainder.3p b/upstream/archlinux/man3p/remainder.3p new file mode 100644 index 00000000..ea498230 --- /dev/null +++ b/upstream/archlinux/man3p/remainder.3p @@ -0,0 +1,147 @@ +'\" et +.TH REMAINDER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +remainder, +remainderf, +remainderl +\(em remainder function +.SH SYNOPSIS +.LP +.nf +#include +.P +double remainder(double \fIx\fP, double \fIy\fP); +float remainderf(float \fIx\fP, float \fIy\fP); +long double remainderl(long double \fIx\fP, long double \fIy\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall return the floating-point remainder +.IR r =\c +.IR x \-\c +.IR ny +when +.IR y +is non-zero. The value +.IR n +is the integral value nearest the exact value +.IR x /\c +.IR y . +When |\|\fIn\fR\-\fIx\fR/\fIy\fR\||=\(12, the value +.IR n +is chosen to be even. +.P +The behavior of +\fIremainder\fR() +shall be independent of the rounding mode. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the +floating-point remainder +.IR r =\c +.IR x \-\c +.IR ny +when +.IR y +is non-zero. +.P +On systems that do not support the IEC 60559 Floating-Point option, if +.IR y +is zero, it is implementation-defined whether a domain error occurs or +zero is returned. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If +.IR x +is infinite or +.IR y +is 0 and the other is non-NaN, a domain error shall occur, and a NaN +shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf, or the +.IR y +argument is \(+-0 and the other argument is non-NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The +.IR y +argument is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabs\fR\^(\|)", +.IR "\fIdiv\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIldiv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/remove.3p b/upstream/archlinux/man3p/remove.3p new file mode 100644 index 00000000..1ff8bd17 --- /dev/null +++ b/upstream/archlinux/man3p/remove.3p @@ -0,0 +1,99 @@ +'\" et +.TH REMOVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +remove +\(em remove a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int remove(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIremove\fR() +function shall cause the file named by the pathname pointed to by +.IR path +to be no longer accessible by that name. A subsequent attempt to open +that file using that name shall fail, unless it is created anew. +.P +If +.IR path +does not name a directory, \fIremove\fP(\fIpath\fP) shall be equivalent +to \fIunlink\fP(\fIpath\fP). +.P +If +.IR path +names a directory, \fIremove\fP(\fIpath\fP) shall be equivalent to +\fIrmdir\fP(\fIpath\fP). +.SH "RETURN VALUE" +Refer to +.IR "\fIrmdir\fR\^(\|)" +or +.IR "\fIunlink\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIrmdir\fR\^(\|)" +or +.IR "\fIunlink\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Removing Access to a File" +.P +The following example shows how to remove access to a file named +.BR /home/cnd/old_mods . +.sp +.RS 4 +.nf + +#include +.P +int status; +\&... +status = remove("/home/cnd/old_mods"); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/remque.3p b/upstream/archlinux/man3p/remque.3p new file mode 100644 index 00000000..6c458662 --- /dev/null +++ b/upstream/archlinux/man3p/remque.3p @@ -0,0 +1,40 @@ +'\" et +.TH REMQUE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +remque +\(em remove an element from a queue +.SH SYNOPSIS +.LP +.nf +#include +.P +void remque(void *\fIelement\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinsque\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/remquo.3p b/upstream/archlinux/man3p/remquo.3p new file mode 100644 index 00000000..1a609f1a --- /dev/null +++ b/upstream/archlinux/man3p/remquo.3p @@ -0,0 +1,163 @@ +'\" et +.TH REMQUO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +remquo, +remquof, +remquol +\(em remainder functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double remquo(double \fIx\fP, double \fIy\fP, int *\fIquo\fP); +float remquof(float \fIx\fP, float \fIy\fP, int *\fIquo\fP); +long double remquol(long double \fIx\fP, long double \fIy\fP, int *\fIquo\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIremquo\fR(), +\fIremquof\fR(), +and +\fIremquol\fR() +functions shall compute the same remainder as the +\fIremainder\fR(), +\fIremainderf\fR(), +and +\fIremainderl\fR() +functions, respectively. In the object pointed to by +.IR quo , +they store a value whose sign is the sign of +.IR x /\c +.IR y +and whose magnitude is congruent modulo 2\fI\s-3\un\d\s+3\fR to the +magnitude of the integral quotient of +.IR x /\c +.IR y , +where +.IR n +is an implementation-defined integer greater than or equal to 3. If +.IR y +is zero, the value stored in the object pointed to by +.IR quo +is unspecified. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +These functions shall return +.IR x +REM +.IR y . +.P +On systems that do not support the IEC 60559 Floating-Point option, if +.IR y +is zero, it is implementation-defined whether a domain error occurs or +zero is returned. +.P +If +.IR x +or +.IR y +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-Inf or +.IR y +is zero and the other argument is non-NaN, a domain error shall occur, +and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf, or the +.IR y +argument is \(+-0 and the other argument is non-NaN. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The +.IR y +argument is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions are intended for implementing argument reductions which +can exploit a few low-order bits of the quotient. Note that +.IR x +may be so large in magnitude relative to +.IR y +that an exact representation of the quotient is not practical. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIremainder\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/rename.3p b/upstream/archlinux/man3p/rename.3p new file mode 100644 index 00000000..383d7ed9 --- /dev/null +++ b/upstream/archlinux/man3p/rename.3p @@ -0,0 +1,555 @@ +'\" et +.TH RENAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +rename, renameat +\(em rename file +.SH SYNOPSIS +.LP +.nf +#include +.P +int rename(const char *\fIold\fP, const char *\fInew\fP); +.P +#include +.P +int renameat(int \fIoldfd\fP, const char *\fIold\fP, int \fInewfd\fP, + const char *\fInew\fP); +.fi +.SH DESCRIPTION +For +\fIrename\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIrename\fR() +function shall change the name of a file. The +.IR old +argument points to the pathname of the file to be renamed. The +.IR new +argument points to the new pathname of the file. +If the +.IR new +argument does not resolve to an existing directory entry for a file of +type directory and the +.IR new +argument contains at least one non-\c + +character and ends with one or more trailing + +characters after all symbolic links have been processed, +\fIrename\fR() +shall fail. +.P +If either the +.IR old +or +.IR new +argument names a symbolic link, +\fIrename\fR() +shall operate on the symbolic link itself, and shall not resolve the +last component of the argument. If the +.IR old +argument and the +.IR new +argument resolve to either the same existing directory entry or different +directory entries for the same existing file, +\fIrename\fR() +shall return successfully and perform no other action. +.P +If the +.IR old +argument points to the pathname of a file that is not a directory, the +.IR new +argument shall not point to the pathname of a directory. If the link +named by the +.IR new +argument exists, it shall be removed and +.IR old +renamed to +.IR new . +In this case, a link named +.IR new +shall remain visible to other threads throughout the renaming operation +and refer either to the file referred to by +.IR new +or +.IR old +before the operation began. Write access permission is required for +both the directory containing +.IR old +and the directory containing +.IR new . +.P +If the +.IR old +argument points to the pathname of a directory, the +.IR new +argument shall not point to the pathname of a file that is not a +directory. If the directory named by the +.IR new +argument exists, it shall be removed and +.IR old +renamed to +.IR new . +In this case, a link named +.IR new +shall exist throughout the renaming operation and shall refer either to +the directory referred to by +.IR new +or +.IR old +before the operation began. If +.IR new +names an existing directory, it shall be required to be an empty +directory. +.P +If either +.IR pathname +argument refers to a path whose final component is either dot or +dot-dot, +\fIrename\fR() +shall fail. +.P +If the +.IR old +argument points to a pathname of a symbolic link, the symbolic link +shall be renamed. If the +.IR new +argument points to a pathname of a symbolic link, the symbolic link +shall be removed. +.P +The +.IR old +pathname shall not name an ancestor directory of the +.IR new +pathname. Write access permission is required for the directory containing +.IR old +and the directory containing +.IR new . +If the +.IR old +argument points to the pathname of a directory, write access permission +may be required for the directory named by +.IR old , +and, if it exists, the directory named by +.IR new . +.P +If the link named by the +.IR new +argument exists and the file's link count becomes 0 when it is removed +and no process has the file open, the space occupied by the file shall +be freed and the file shall no longer be accessible. If one or more +processes have the file open when the last link is removed, the link +shall be removed before +\fIrename\fR() +returns, but the removal of the file contents shall be postponed until +all references to the file are closed. +.P +Upon successful completion, +\fIrename\fR() +shall mark for update the last data modification and last file status +change timestamps of the parent directory of each file. +.P +If the +\fIrename\fR() +function fails for any reason other than +.BR [EIO] , +any file named by +.IR new +shall be unaffected. +.P +The +\fIrenameat\fR() +function shall be equivalent to the +\fIrename\fR() +function except in the case where either +.IR old +or +.IR new +specifies a relative path. If +.IR old +is a relative path, the file to be renamed is located relative to the +directory associated with the file descriptor +.IR oldfd +instead of the current working directory. If +.IR new +is a relative path, the same happens only relative to the directory +associated with +.IR newfd . +If the access mode of the open file description associated with the +file descriptor is not O_SEARCH, the function shall check whether +directory searches are permitted using the current permissions of +the directory underlying the file descriptor. If the access mode is +O_SEARCH, the function shall not perform the check. +.P +If +\fIrenameat\fR() +is passed the special value AT_FDCWD in the +.IR oldfd +or +.IR newfd +parameter, the current working directory shall be used in the +determination of the file for the respective +.IR path +parameter. +.SH "RETURN VALUE" +Upon successful completion, the +\fIrename\fR() +function shall return 0. Otherwise, it shall return \-1, +.IR errno +shall be set to indicate the error, +and neither the file named by +.IR old +nor the file named by +.IR new +shall be changed or created. +.P +Upon successful completion, the +\fIrenameat\fR() +function shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIrename\fR() +and +\fIrenameat\fR() +functions shall fail if: +.TP +.BR EACCES +A component of either path prefix denies search permission; or one of +the directories containing +.IR old +or +.IR new +denies write permissions; or, write permission is required and is +denied for a directory pointed to by the +.IR old +or +.IR new +arguments. +.TP +.BR EBUSY +The directory named by +.IR old +or +.IR new +is currently in use by the system or another process, and the +implementation considers this an error. +.IP "[EEXIST]\ or\ [ENOTEMPTY]" 12 +.br +The link named by +.IR new +is a directory that is not an empty directory. +.TP +.BR EINVAL +The +.IR old +pathname names an ancestor directory of the +.IR new +pathname, or either pathname argument contains a final component that +is dot or dot-dot. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR EISDIR +The +.IR new +argument points to a directory and the +.IR old +argument points to a file that is not a directory. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR EMLINK +The file named by +.IR old +is a directory, and the link count of the parent directory of +.IR new +would exceed +{LINK_MAX}. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +The link named by +.IR old +does not name an existing file, a component of the path prefix of +.IR new +does not exist, or either +.IR old +or +.IR new +points to an empty string. +.TP +.BR ENOSPC +The directory that would contain +.IR new +cannot be extended. +.TP +.BR ENOTDIR +A component of either path prefix names an existing file that is +neither a directory nor a symbolic link to a directory; or the +.IR old +argument names a directory and the +.IR new +argument names a non-directory file; or the +.IR old +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory; or the +.IR old +argument names an existing non-directory file and the +.IR new +argument names a nonexistent file, contains at least one non-\c + +character, and ends with one or more trailing + +characters; or the +.IR new +argument names an existing non-directory file, contains at least one non-\c + +character, and ends with one or more trailing + +characters. +.TP +.BR EPERM " or " EACCES +.br +The S_ISVTX flag is set on the directory containing the file referred +to by +.IR old +and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection" +with respect to +.IR old ; +or +.IR new +refers to an existing file, the S_ISVTX flag is set on the directory +containing this file, and the process does not satisfy the criteria +specified in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection" +with respect to this file. +.TP +.BR EROFS +The requested operation requires writing in a directory on a read-only +file system. +.TP +.BR EXDEV +The links named by +.IR new +and +.IR old +are on different file systems and the implementation does not support +links between file systems. +.P +In addition, the +\fIrenameat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR oldfd +or +.IR newfd +is not O_SEARCH and the permissions of the directory underlying +.IR oldfd +or +.IR newfd , +respectively, do not permit directory searches. +.TP +.BR EBADF +The +.IR old +argument does not specify an absolute path and the +.IR oldfd +argument is neither AT_FDCWD nor a valid file descriptor open for +reading or searching, or the +.IR new +argument does not specify an absolute path and the +.IR newfd +argument is neither AT_FDCWD nor a valid file descriptor open +for reading or searching. +.TP +.BR ENOTDIR +The +.IR old +or +.IR new +argument is not an absolute path and +.IR oldfd +or +.IR newfd , +respectively, is a file descriptor associated with a non-directory file. +.P +The +\fIrename\fR() +and +\fIrenameat\fR() +functions may fail if: +.TP +.BR EBUSY +The file named by the +.IR old +or +.IR new +arguments is a named STREAM. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The file named by +.IR new +exists and is the last directory entry to a pure procedure (shared text) +file that is being executed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Renaming a File" +.P +The following example shows how to rename a file named +.BR /home/cnd/mod1 +to +.BR /home/cnd/mod2 . +.sp +.RS 4 +.nf + +#include +.P +int status; +\&... +status = rename("/home/cnd/mod1", "/home/cnd/mod2"); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Some implementations mark for update the last file status change timestamp +of renamed files and some do not. Applications which make use of the +last file status change timestamp may behave differently with respect +to renamed files unless they are designed to allow for either behavior. +.SH RATIONALE +This +\fIrename\fR() +function is equivalent for regular files to that defined by the ISO\ C standard. +Its inclusion here expands that definition to include actions on +directories and specifies behavior when the +.IR new +parameter names a file that already exists. That specification +requires that the action of the function be atomic. +.P +One of the reasons for introducing this function was to have a means of +renaming directories while permitting implementations to prohibit the +use of +\fIlink\fR() +and +\fIunlink\fR() +with directories, thus constraining links to directories to those made by +\fImkdir\fR(). +.P +The specification that if +.IR old +and +.IR new +refer to the same file is intended to guarantee that: +.sp +.RS 4 +.nf + +rename("x", "x"); +.fi +.P +.RE +.P +does not remove the file. +.P +Renaming dot or dot-dot is prohibited in order to prevent cyclical file +system paths. +.P +See also the descriptions of +.BR [ENOTEMPTY] +and +.BR [ENAMETOOLONG] +in +\fIrmdir\fR() +and +.BR [EBUSY] +in +\fIunlink\fR(). +For a discussion of +.BR [EXDEV] , +see +\fIlink\fR(). +.P +The purpose of the +\fIrenameat\fR() +function is to rename files in directories other than the current +working directory without exposure to race conditions. Any part of the +path of a file could be changed in parallel to a call to +\fIrename\fR(), +resulting in unspecified behavior. By opening file descriptors for the +source and target directories and using the +\fIrenameat\fR() +function it can be guaranteed that that renamed file is located correctly +and the resulting file is in the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlink\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/rewind.3p b/upstream/archlinux/man3p/rewind.3p new file mode 100644 index 00000000..7e966719 --- /dev/null +++ b/upstream/archlinux/man3p/rewind.3p @@ -0,0 +1,102 @@ +'\" et +.TH REWIND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +rewind +\(em reset the file position indicator in a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void rewind(FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The call: +.sp +.RS 4 +.nf + +rewind(stream) +.fi +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf + +(void) fseek(stream, 0L, SEEK_SET) +.fi +.P +.RE +.P +except that +\fIrewind\fR() +shall also clear the error indicator. +.P +Since +\fIrewind\fR() +does not return a value, an application wishing to detect errors should +clear +.IR errno , +then call +\fIrewind\fR(), +and if +.IR errno +is non-zero, assume an error has occurred. +.SH "RETURN VALUE" +The +\fIrewind\fR() +function shall not return a value. +.SH ERRORS +Refer to +.IR "\fIfseek\fR\^(\|)" +with the exception of +.BR [EINVAL] +which does not apply. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfseek\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/rewinddir.3p b/upstream/archlinux/man3p/rewinddir.3p new file mode 100644 index 00000000..9b40280c --- /dev/null +++ b/upstream/archlinux/man3p/rewinddir.3p @@ -0,0 +1,93 @@ +'\" et +.TH REWINDDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +rewinddir +\(em reset the position of a directory stream to the beginning +of a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +void rewinddir(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fIrewinddir\fR() +function shall reset the position of the directory stream to which +.IR dirp +refers to the beginning of the directory. It shall also cause the +directory stream to refer to the current state of the corresponding +directory, as a call to +\fIopendir\fR() +would have done. If +.IR dirp +does not refer to a directory stream, the effect is undefined. +.P +After a call to the +\fIfork\fR() +function, either the parent or child (but not both) may continue +processing the directory stream using +\fIreaddir\fR(), +\fIrewinddir\fR(), +or +\fIseekdir\fR(). +If both the parent and child processes use these functions, the result +is undefined. +.SH "RETURN VALUE" +The +\fIrewinddir\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIrewinddir\fR() +function should be used in conjunction with +\fIopendir\fR(), +\fIreaddir\fR(), +and +\fIclosedir\fR() +to examine the contents of the directory. This method is recommended +for portability. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclosedir\fR\^(\|)", +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/rint.3p b/upstream/archlinux/man3p/rint.3p new file mode 100644 index 00000000..4a3194d4 --- /dev/null +++ b/upstream/archlinux/man3p/rint.3p @@ -0,0 +1,132 @@ +'\" et +.TH RINT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +rint, +rintf, +rintl +\(em round-to-nearest integral value +.SH SYNOPSIS +.LP +.nf +#include +.P +double rint(double \fIx\fP); +float rintf(float \fIx\fP); +long double rintl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall return the integral value (represented as a +.BR double ) +nearest +.IR x +in the direction of the current rounding mode. The current rounding +mode is implementation-defined. +.P +If the current rounding mode rounds toward negative infinity, then +\fIrint\fR() +shall be equivalent to +.IR "\fIfloor\fR\^(\|)". +If the current rounding mode rounds toward positive infinity, then +\fIrint\fR() +shall be equivalent to +.IR "\fIceil\fR\^(\|)". +If the current rounding mode rounds towards zero, then +\fIrint\fR() +shall be equivalent to +.IR "\fItrunc\fR\^(\|)". +If the current rounding mode rounds towards nearest, then +\fIrint\fR() +differs from +.IR "\fIround\fR\^(\|)" +in that halfway cases are rounded to even rather than away from zero. +.P +These functions differ from the +\fInearbyint\fR(), +\fInearbyintf\fR(), +and +\fInearbyintl\fR() +functions only in that they may raise the inexact floating-point +exception if the result differs in value from the argument. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the integer +(represented as a double precision number) nearest +.IR x +in the direction of the current rounding mode. +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer type +to avoid the undefined results of an integer overflow. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIabs\fR\^(\|)", +.IR "\fIceil\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIfloor\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fInearbyint\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/rmdir.3p b/upstream/archlinux/man3p/rmdir.3p new file mode 100644 index 00000000..3fdfef75 --- /dev/null +++ b/upstream/archlinux/man3p/rmdir.3p @@ -0,0 +1,269 @@ +'\" et +.TH RMDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +rmdir +\(em remove a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int rmdir(const char *\fIpath\fP); +.fi +.SH DESCRIPTION +The +\fIrmdir\fR() +function shall remove a directory whose name is given by +.IR path . +The directory shall be removed only if it is an empty directory. +.P +If the directory is the root directory or the current working directory +of any process, it is unspecified whether the function succeeds, or +whether it shall fail and set +.IR errno +to +.BR [EBUSY] . +.P +If +.IR path +names a symbolic link, then +\fIrmdir\fR() +shall fail and set +.IR errno +to +.BR [ENOTDIR] . +.P +If the +.IR path +argument refers to a path whose final component is either dot or +dot-dot, +\fIrmdir\fR() +shall fail. +.P +If the directory's link count becomes 0 and no process has the +directory open, the space occupied by the directory shall be freed and +the directory shall no longer be accessible. If one or more processes +have the directory open when the last link is removed, the dot and +dot-dot entries, if present, shall be removed before +\fIrmdir\fR() +returns and no new entries may be created in the directory, but the +directory shall not be removed until all references to the directory +are closed. +.P +If the directory is not an empty directory, +\fIrmdir\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] +or +.BR [ENOTEMPTY] . +.P +Upon successful completion, +\fIrmdir\fR() +shall mark for update the last data modification and last file status +change timestamps of the parent directory. +.SH "RETURN VALUE" +Upon successful completion, the function +\fIrmdir\fR() +shall return 0. Otherwise, \-1 shall be returned, and +.IR errno +set to indicate the error. If \-1 is returned, the named +directory shall not be changed. +.SH ERRORS +The +\fIrmdir\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied on a component of the path prefix, or write +permission is denied on the parent directory of the directory to be +removed. +.TP +.BR EBUSY +The directory to be removed is currently in use by the system or +some process and the implementation considers this to be an error. +.IP "[EEXIST]\ or\ [ENOTEMPTY]" 12 +.br +The +.IR path +argument names a directory that is not an empty directory, or there are +hard links to the directory other than dot or a single entry in +dot-dot. +.TP +.BR EINVAL +The +.IR path +argument contains a last component that is dot. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file, or the +.IR path +argument names a nonexistent directory or points to an empty string. +.TP +.BR ENOTDIR +A component of +.IR path +names an existing file that is neither a directory nor a symbolic link +to a directory. +.IP "[EPERM]\ or\ [EACCES]" 12 +.br +The S_ISVTX flag is set on the directory containing the file referred +to by the +.IR path +argument and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection". +.TP +.BR EROFS +The directory entry to be removed resides on a read-only file system. +.P +The +\fIrmdir\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Removing a Directory" +.P +The following example shows how to remove a directory named +.BR /home/cnd/mod1 . +.sp +.RS 4 +.nf + +#include +.P +int status; +\&... +status = rmdir("/home/cnd/mod1"); +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIrmdir\fR() +and +\fIrename\fR() +functions originated in 4.2 BSD, and they used +.BR [ENOTEMPTY] +for the condition when the directory to be removed does not exist or +.IR new +already exists. When the 1984 /usr/group standard was published, it contained +.BR [EEXIST] +instead. When these functions were adopted into System V, the +1984 /usr/group standard was used as a reference. Therefore, several existing applications +and implementations support/use both forms, and no agreement could be +reached on either value. All implementations are required to supply +both +.BR [EEXIST] +and +.BR [ENOTEMPTY] +in +.IR +with distinct values, so that applications can use both values in +C-language +.BR case +statements. +.P +The meaning of deleting +.IR pathname \c +.BR /dot +is unclear, because the name of the file (directory) in the parent +directory to be removed is not clear, particularly in the presence of +multiple links to a directory. +.P +The POSIX.1\(hy1990 standard was silent with regard to the behavior of +\fIrmdir\fR() +when there are multiple hard links to the directory being removed. The +requirement to set +.IR errno +to +.BR [EEXIST] +or +.BR [ENOTEMPTY] +clarifies the behavior in this case. +.P +If the current working directory of the process is being removed, that +should be an allowed error. +.P +Virtually all existing implementations detect +.BR [ENOTEMPTY] +or the case of dot-dot. The text in +.IR "Section 2.3" ", " "Error Numbers" +about returning any one of the possible errors permits that behavior to +continue. The +.BR [ELOOP] +error may be returned if more than +{SYMLOOP_MAX} +symbolic links are encountered during resolution of the +.IR path +argument. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.3" ", " "Error Numbers", +.IR "\fImkdir\fR\^(\|)", +.IR "\fIremove\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/round.3p b/upstream/archlinux/man3p/round.3p new file mode 100644 index 00000000..ddd53e66 --- /dev/null +++ b/upstream/archlinux/man3p/round.3p @@ -0,0 +1,90 @@ +'\" et +.TH ROUND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +round, +roundf, +roundl +\(em round to the nearest integer value in a floating-point format +.SH SYNOPSIS +.LP +.nf +#include +.P +double round(double \fIx\fP); +float roundf(float \fIx\fP); +long double roundl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall round their argument to the nearest integer value +in floating-point format, rounding halfway cases away from zero, +regardless of the current rounding direction. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the rounded +integer value. +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer +type to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/scalbln.3p b/upstream/archlinux/man3p/scalbln.3p new file mode 100644 index 00000000..788ce427 --- /dev/null +++ b/upstream/archlinux/man3p/scalbln.3p @@ -0,0 +1,174 @@ +'\" et +.TH SCALBLN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +scalbln, +scalblnf, +scalblnl, +scalbn, +scalbnf, +scalbnl +\(em compute exponent using FLT_RADIX +.SH SYNOPSIS +.LP +.nf +#include +.P +double scalbln(double \fIx\fP, long \fIn\fP); +float scalblnf(float \fIx\fP, long \fIn\fP); +long double scalblnl(long double \fIx\fP, long \fIn\fP); +double scalbn(double \fIx\fP, int \fIn\fP); +float scalbnf(float \fIx\fP, int \fIn\fP); +long double scalbnl(long double \fIx\fP, int \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute \fIx\fR\ *\ FLT_RADIX\fI\s-3\un\d\s+3\fR +efficiently, not normally by computing FLT_RADIX\fI\s-3\un\d\s+3\fR +explicitly. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return +\fIx\fR\ *\ FLT_RADIX\fI\s-3\un\d\s+3\fR. +.P +If the result would cause overflow, a range error shall occur and these +functions shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL +(according to the sign of +.IR x ) +as appropriate for the return type of the function. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fIscalbln\fR(), +\fIscalblnf\fR(), +\fIscalblnl\fR(), +\fIscalbn\fR(), +\fIscalbnf\fR(), +and +\fIscalbnl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, LDBL_MIN, DBL_MIN, +FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR n +is 0, +.IR x +shall be returned. +.P +If the correct value would cause underflow, and is representable, a +range error may occur and the correct value shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +These functions are named so as to avoid conflicting with the +historical definition of the +.IR scalb (\|) +function from the Single UNIX Specification. The difference is that the +.IR scalb (\|) +function has a second argument of +.BR double +instead of +.BR int . +The +.IR scalb (\|) +function is not part of the ISO\ C standard. The three functions whose second +type is +.BR long +are provided because the factor required to scale from the smallest +positive floating-point value to the largest finite one, on many +implementations, is too large to represent in the minimum-width +.BR int +format. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/scandir.3p b/upstream/archlinux/man3p/scandir.3p new file mode 100644 index 00000000..c786f7a1 --- /dev/null +++ b/upstream/archlinux/man3p/scandir.3p @@ -0,0 +1,42 @@ +'\" et +.TH SCANDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +scandir +\(em scan a directory +.SH SYNOPSIS +.LP +.nf +#include +.P +int scandir(const char *\fIdir\fP, struct dirent ***\fInamelist\fP, + int (*\fIsel\fP)(const struct dirent *), + int (*\fIcompar\fP)(const struct dirent **, const struct dirent **)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIalphasort\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/scanf.3p b/upstream/archlinux/man3p/scanf.3p new file mode 100644 index 00000000..8f1c4240 --- /dev/null +++ b/upstream/archlinux/man3p/scanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH SCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +scanf +\(em convert formatted input +.SH SYNOPSIS +.LP +.nf +#include +.P +int scanf(const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sched_get_priority_max.3p b/upstream/archlinux/man3p/sched_get_priority_max.3p new file mode 100644 index 00000000..adb5ecc7 --- /dev/null +++ b/upstream/archlinux/man3p/sched_get_priority_max.3p @@ -0,0 +1,95 @@ +'\" et +.TH SCHED_GET_PRIORITY_MAX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sched_get_priority_max, +sched_get_priority_min +\(em get priority limits +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_get_priority_max(int \fIpolicy\fP); +int sched_get_priority_min(int \fIpolicy\fP); +.fi +.SH DESCRIPTION +The +\fIsched_get_priority_max\fR() +and +\fIsched_get_priority_min\fR() +functions shall return the appropriate maximum or minimum, +respectively, for the scheduling policy specified by +.IR policy . +.P +The value of +.IR policy +shall be one of the scheduling policy values defined in +.IR . +.SH "RETURN VALUE" +If successful, the +\fIsched_get_priority_max\fR() +and +\fIsched_get_priority_min\fR() +functions shall return the appropriate maximum or minimum values, +respectively. If unsuccessful, they shall return a value of \-1 and +set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_get_priority_max\fR() +and +\fIsched_get_priority_min\fR() +functions shall fail if: +.TP +.BR EINVAL +The value of the +.IR policy +parameter does not represent a defined scheduling policy. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_rr_get_interval\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sched_getparam.3p b/upstream/archlinux/man3p/sched_getparam.3p new file mode 100644 index 00000000..942f019b --- /dev/null +++ b/upstream/archlinux/man3p/sched_getparam.3p @@ -0,0 +1,100 @@ +'\" et +.TH SCHED_GETPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sched_getparam +\(em get scheduling parameters +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_getparam(pid_t \fIpid\fP, struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIsched_getparam\fR() +function shall return the scheduling parameters of a process specified by +.IR pid +in the +.BR sched_param +structure pointed to by +.IR param . +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +parameters for the process whose process ID is equal to +.IR pid +shall be returned. +.P +If +.IR pid +is zero, the scheduling parameters for the calling process shall be +returned. The behavior of the +\fIsched_getparam\fR() +function is unspecified if the value of +.IR pid +is negative. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsched_getparam\fR() +function shall return zero. If the call to +\fIsched_getparam\fR() +is unsuccessful, the function shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_getparam\fR() +function shall fail if: +.TP +.BR EPERM +The requesting process does not have permission to obtain the +scheduling parameters of the specified process. +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sched_getscheduler.3p b/upstream/archlinux/man3p/sched_getscheduler.3p new file mode 100644 index 00000000..ff43efa7 --- /dev/null +++ b/upstream/archlinux/man3p/sched_getscheduler.3p @@ -0,0 +1,100 @@ +'\" et +.TH SCHED_GETSCHEDULER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sched_getscheduler +\(em get scheduling policy +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_getscheduler(pid_t \fIpid\fP); +.fi +.SH DESCRIPTION +The +\fIsched_getscheduler\fR() +function shall return the scheduling policy of the process specified by +.IR pid . +If the value of +.IR pid +is negative, the behavior of the +\fIsched_getscheduler\fR() +function is unspecified. +.P +The values that can be returned by +\fIsched_getscheduler\fR() +are defined in the +.IR +header. +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +policy shall be returned for the process whose process ID is equal to +.IR pid . +.P +If +.IR pid +is zero, the scheduling policy shall be returned for the calling process. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsched_getscheduler\fR() +function shall return the scheduling policy of the specified process. +If unsuccessful, the function shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_getscheduler\fR() +function shall fail if: +.TP +.BR EPERM +The requesting process does not have permission to determine the +scheduling policy of the specified process. +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sched_rr_get_interval.3p b/upstream/archlinux/man3p/sched_rr_get_interval.3p new file mode 100644 index 00000000..25e73b7d --- /dev/null +++ b/upstream/archlinux/man3p/sched_rr_get_interval.3p @@ -0,0 +1,88 @@ +'\" et +.TH SCHED_RR_GET_INTERVAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sched_rr_get_interval +\(em get execution time limits +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_rr_get_interval(pid_t \fIpid\fP, struct timespec *\fIinterval\fP); +.fi +.SH DESCRIPTION +The +\fIsched_rr_get_interval\fR() +function shall update the +.BR timespec +structure referenced by the +.IR interval +argument to contain the current execution time limit (that is, time +quantum) for the process specified by +.IR pid . +If +.IR pid +is zero, the current execution time limit for the calling process +shall be returned. +.SH "RETURN VALUE" +If successful, the +\fIsched_rr_get_interval\fR() +function shall return zero. Otherwise, it shall return a value of +\-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_rr_get_interval\fR() +function shall fail if: +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_get_priority_max\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sched_setparam.3p b/upstream/archlinux/man3p/sched_setparam.3p new file mode 100644 index 00000000..df532fb0 --- /dev/null +++ b/upstream/archlinux/man3p/sched_setparam.3p @@ -0,0 +1,159 @@ +'\" et +.TH SCHED_SETPARAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sched_setparam +\(em set scheduling parameters +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_setparam(pid_t \fIpid\fP, const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIsched_setparam\fR() +function shall set the scheduling parameters of the process specified by +.IR pid +to the values specified by the +.BR sched_param +structure pointed to by +.IR param . +The value of the +.IR sched_priority +member in the +.BR sched_param +structure shall be any integer within the inclusive priority range for +the current scheduling policy of the process specified by +.IR pid . +Higher numerical values for the priority represent higher priorities. +If the value of +.IR pid +is negative, the behavior of the +\fIsched_setparam\fR() +function is unspecified. +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +parameters shall be set for the process whose process ID is equal to +.IR pid . +.P +If +.IR pid +is zero, the scheduling parameters shall be set for the calling process. +.P +The conditions under which one process has permission to change the +scheduling parameters of another process are implementation-defined. +.P +Implementations may require the requesting process to have appropriate +privileges to set its own scheduling parameters or those of another +process. +.P +See +.IR "Scheduling Policies" +for a description on how this function affects the scheduling of +the threads within the target process. +.P +If the current scheduling policy for the target process is not +SCHED_FIFO, SCHED_RR, +or SCHED_SPORADIC, +the result is implementation-defined; this case includes the +SCHED_OTHER policy. +.P +The specified +.IR sched_ss_repl_period +shall be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. +.P +The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,{SS_REPL_MAX}] for the function +to succeed; if not, the function shall fail. It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +This function is not atomic with respect to other threads in the +process. Threads may continue to execute while this function call is in +the process of changing the scheduling policy for the underlying +kernel-scheduled entities used by the process contention scope +threads. +.SH "RETURN VALUE" +If successful, the +\fIsched_setparam\fR() +function shall return zero. +.P +If the call to +\fIsched_setparam\fR() +is unsuccessful, the priority shall remain unchanged, and the function +shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_setparam\fR() +function shall fail if: +.TP +.BR EINVAL +One or more of the requested scheduling parameters is outside the range +defined for the scheduling policy of the specified +.IR pid . +.TP +.BR EPERM +The requesting process does not have permission to set the scheduling +parameters for the specified process, or does not have appropriate +privileges to invoke +\fIsched_setparam\fR(). +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Scheduling Policies", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setscheduler\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sched_setscheduler.3p b/upstream/archlinux/man3p/sched_setscheduler.3p new file mode 100644 index 00000000..193d8bce --- /dev/null +++ b/upstream/archlinux/man3p/sched_setscheduler.3p @@ -0,0 +1,184 @@ +'\" et +.TH SCHED_SETSCHEDULER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sched_setscheduler +\(em set scheduling policy and parameters +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_setscheduler(pid_t \fIpid\fP, int \fIpolicy\fP, + const struct sched_param *\fIparam\fP); +.fi +.SH DESCRIPTION +The +\fIsched_setscheduler\fR() +function shall set the scheduling policy and scheduling parameters +of the process specified by +.IR pid +to +.IR policy +and the parameters specified in the +.BR sched_param +structure pointed to by +.IR param , +respectively. The value of the +.IR sched_priority +member in the +.BR sched_param +structure shall be any integer within the inclusive priority range +for the scheduling policy specified by +.IR policy . +If the value of +.IR pid +is negative, the behavior of the +\fIsched_setscheduler\fR() +function is unspecified. +.P +The possible values for the +.IR policy +parameter are defined in the +.IR +header. +.P +If a process specified by +.IR pid +exists, and if the calling process has permission, the scheduling +policy and scheduling parameters shall be set for the process whose +process ID is equal to +.IR pid . +.P +If +.IR pid +is zero, the scheduling policy and scheduling parameters shall be +set for the calling process. +.P +The conditions under which one process has appropriate privileges to +change the scheduling parameters of another process are +implementation-defined. +.P +Implementations may require that the requesting process have permission +to set its own scheduling parameters or those of another process. +Additionally, implementation-defined restrictions may apply as to the +appropriate privileges required to set the scheduling +policy of the process, or the scheduling policy of another process, +to a particular value. +.P +The +\fIsched_setscheduler\fR() +function shall be considered successful if it succeeds in setting the +scheduling policy and scheduling parameters of the process specified by +.IR pid +to the values specified by +.IR policy +and the structure pointed to by +.IR param , +respectively. +.P +See +.IR "Scheduling Policies" +for a description on how this function affects the scheduling of the +threads within the target process. +.P +If the current scheduling policy for the target process is not +SCHED_FIFO, SCHED_RR, +or SCHED_SPORADIC, +the result is implementation-defined; this case includes the +SCHED_OTHER policy. +.P +The specified +.IR sched_ss_repl_period +shall be greater than or equal to the specified +.IR sched_ss_init_budget +for the function to succeed; if it is not, then the function shall +fail. +.P +The value of +.IR sched_ss_max_repl +shall be within the inclusive range [1,{SS_REPL_MAX}] for the function +to succeed; if not, the function shall fail. It is unspecified whether the +.IR sched_ss_repl_period +and +.IR sched_ss_init_budget +values are stored as provided by this function or are rounded to +align with the resolution of the clock being used. +.P +This function is not atomic with respect to other threads in the +process. Threads may continue to execute while this function call is in +the process of changing the scheduling policy and associated scheduling +parameters for the underlying kernel-scheduled entities used by the +process contention scope threads. +.SH "RETURN VALUE" +Upon successful completion, the function shall return the former +scheduling policy of the specified process. If the +\fIsched_setscheduler\fR() +function fails to complete successfully, the policy and scheduling +parameters shall remain unchanged, and the function shall return a +value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsched_setscheduler\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR policy +parameter is invalid, or one or more of the parameters contained in +.IR param +is outside the valid range for the specified scheduling policy. +.TP +.BR EPERM +The requesting process does not have permission to set either or both +of the scheduling parameters or the scheduling policy of the specified +process. +.TP +.BR ESRCH +No process can be found corresponding to that specified by +.IR pid . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Scheduling Policies", +.IR "\fIsched_getparam\fR\^(\|)", +.IR "\fIsched_getscheduler\fR\^(\|)", +.IR "\fIsched_setparam\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sched_yield.3p b/upstream/archlinux/man3p/sched_yield.3p new file mode 100644 index 00000000..aa3b44ac --- /dev/null +++ b/upstream/archlinux/man3p/sched_yield.3p @@ -0,0 +1,69 @@ +'\" et +.TH SCHED_YIELD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sched_yield +\(em yield the processor +.SH SYNOPSIS +.LP +.nf +#include +.P +int sched_yield(void); +.fi +.SH DESCRIPTION +The +\fIsched_yield\fR() +function shall force the running thread to relinquish the processor +until it again becomes the head of its thread list. It takes no arguments. +.SH "RETURN VALUE" +The +\fIsched_yield\fR() +function shall return 0 if it completes successfully; otherwise, it +shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The conceptual model for scheduling semantics in POSIX.1\(hy2008 defines +a set of thread lists. This set of thread lists is always present +regardless of the scheduling options supported by the system. On a +system where the Process Scheduling option is not supported, portable +applications should not make any assumptions regarding whether threads +from other processes will be on the same thread list. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/seed48.3p b/upstream/archlinux/man3p/seed48.3p new file mode 100644 index 00000000..ba9b5adc --- /dev/null +++ b/upstream/archlinux/man3p/seed48.3p @@ -0,0 +1,41 @@ +'\" et +.TH SEED48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +seed48 +\(em seed a uniformly distributed pseudo-random non-negative +long integer generator +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned short *seed48(unsigned short \fIseed16v\fP[3]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/seekdir.3p b/upstream/archlinux/man3p/seekdir.3p new file mode 100644 index 00000000..164b5629 --- /dev/null +++ b/upstream/archlinux/man3p/seekdir.3p @@ -0,0 +1,119 @@ +'\" et +.TH SEEKDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +seekdir +\(em set the position of a directory stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void seekdir(DIR *\fIdirp\fP, long \fIloc\fP); +.fi +.SH DESCRIPTION +The +\fIseekdir\fR() +function shall set the position of the next +\fIreaddir\fR() +operation on the directory stream specified by +.IR dirp +to the position specified by +.IR loc . +The value of +.IR loc +should have been returned from an earlier call to +\fItelldir\fR() +using the same directory stream. The new position reverts to the one +associated with the directory stream when +\fItelldir\fR() +was performed. +.P +If the value of +.IR loc +was not obtained from an earlier call to +\fItelldir\fR(), +or if a call to +\fIrewinddir\fR() +occurred between the call to +\fItelldir\fR() +and the call to +\fIseekdir\fR(), +the results of subsequent calls to +\fIreaddir\fR() +are unspecified. +.SH "RETURN VALUE" +The +\fIseekdir\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The original standard developers perceived that there were restrictions +on the use of the +\fIseekdir\fR() +and +\fItelldir\fR() +functions related to implementation details, and for that reason these +functions need not be supported on all POSIX-conforming systems. They +are required on implementations supporting the XSI option. +.P +One of the perceived problems of implementation is that returning to a +given point in a directory is quite difficult to describe formally, in +spite of its intuitive appeal, when systems that use B-trees, hashing +functions, or other similar mechanisms to order their directories are +considered. The definition of +\fIseekdir\fR() +and +\fItelldir\fR() +does not specify whether, when using these interfaces, a given +directory entry will be seen at all, or more than once. +.P +On systems not supporting these functions, their capability can +sometimes be accomplished by saving a filename found by +\fIreaddir\fR() +and later using +\fIrewinddir\fR() +and a loop on +\fIreaddir\fR() +to relocate the position from which the filename was saved. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fItelldir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/select.3p b/upstream/archlinux/man3p/select.3p new file mode 100644 index 00000000..fd48b77c --- /dev/null +++ b/upstream/archlinux/man3p/select.3p @@ -0,0 +1,42 @@ +'\" et +.TH SELECT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +select +\(em synchronous I/O multiplexing +.SH SYNOPSIS +.LP +.nf +#include +.P +int select(int \fInfds\fP, fd_set *restrict \fIreadfds\fP, + fd_set *restrict \fIwritefds\fP, fd_set *restrict \fIerrorfds\fP, + struct timeval *restrict \fItimeout\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpselect\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_close.3p b/upstream/archlinux/man3p/sem_close.3p new file mode 100644 index 00000000..a3c40a00 --- /dev/null +++ b/upstream/archlinux/man3p/sem_close.3p @@ -0,0 +1,105 @@ +'\" et +.TH SEM_CLOSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_close +\(em close a named semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_close(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_close\fR() +function shall indicate that the calling process is finished using +the named semaphore indicated by +.IR sem . +The effects of calling +\fIsem_close\fR() +for an unnamed semaphore (one created by +\fIsem_init\fR()) +are undefined. The +\fIsem_close\fR() +function shall deallocate (that is, make available for reuse by a +subsequent +\fIsem_open\fR() +by this process) any system resources allocated by the system for use +by this process for this semaphore. The effect of subsequent use of the +semaphore indicated by +.IR sem +by this process is undefined. If any threads in the calling process are +currently blocked on the semaphore, the behavior is undefined. +If the semaphore has not been removed with a successful call to +\fIsem_unlink\fR(), +then +\fIsem_close\fR() +has no effect on the state of the semaphore. If the +\fIsem_unlink\fR() +function has been successfully invoked for +.IR name +after the most recent call to +\fIsem_open\fR() +with O_CREAT for this semaphore, +then when all processes that have opened the semaphore close it, the +semaphore is no longer accessible. +.SH "RETURN VALUE" +Upon successful completion, a value of zero shall be returned. +Otherwise, a value of \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsem_close\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument is not a valid semaphore descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_destroy.3p b/upstream/archlinux/man3p/sem_destroy.3p new file mode 100644 index 00000000..7731cf08 --- /dev/null +++ b/upstream/archlinux/man3p/sem_destroy.3p @@ -0,0 +1,95 @@ +'\" et +.TH SEM_DESTROY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_destroy +\(em destroy an unnamed semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_destroy(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_destroy\fR() +function shall destroy the unnamed semaphore indicated by +.IR sem . +Only a semaphore that was created using +\fIsem_init\fR() +may be destroyed using +\fIsem_destroy\fR(); +the effect of calling +\fIsem_destroy\fR() +with a named semaphore is undefined. The effect of subsequent use of +the semaphore +.IR sem +is undefined until +.IR sem +is reinitialized by another call to +\fIsem_init\fR(). +.P +It is safe to destroy an initialized semaphore upon which no threads +are currently blocked. The effect of destroying a semaphore upon which +other threads are currently blocked is undefined. +.SH "RETURN VALUE" +Upon successful completion, a value of zero shall be returned. Otherwise, +a value of \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsem_destroy\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument is not a valid semaphore. +.TP +.BR EBUSY +There are currently processes blocked on the semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_getvalue.3p b/upstream/archlinux/man3p/sem_getvalue.3p new file mode 100644 index 00000000..55713c20 --- /dev/null +++ b/upstream/archlinux/man3p/sem_getvalue.3p @@ -0,0 +1,92 @@ +'\" et +.TH SEM_GETVALUE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_getvalue +\(em get the value of a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_getvalue(sem_t *restrict \fIsem\fP, int *restrict \fIsval\fP); +.fi +.SH DESCRIPTION +The +\fIsem_getvalue\fR() +function shall update the location referenced by the +.IR sval +argument to have the value of the semaphore referenced by +.IR sem +without affecting the state of the semaphore. The updated value +represents an actual semaphore value that occurred at some unspecified +time during the call, but it need not be the actual value of the +semaphore when it is returned to the calling process. +.P +If +.IR sem +is locked, then the object to which +.IR sval +points shall either be set to zero or to a negative number whose +absolute value represents the number of processes waiting for the +semaphore at some unspecified time during the call. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_getvalue\fR() +function shall return a value of zero. Otherwise, it shall return +a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_getvalue\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_init.3p b/upstream/archlinux/man3p/sem_init.3p new file mode 100644 index 00000000..75a08299 --- /dev/null +++ b/upstream/archlinux/man3p/sem_init.3p @@ -0,0 +1,137 @@ +'\" et +.TH SEM_INIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_init +\(em initialize an unnamed semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_init(sem_t *\fIsem\fP, int \fIpshared\fP, unsigned \fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIsem_init\fR() +function shall initialize the unnamed semaphore referred to by +.IR sem . +The value of the initialized semaphore shall be +.IR value . +Following a successful call to +\fIsem_init\fR(), +the semaphore may be used in subsequent calls to +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR(). +This semaphore shall remain usable until the semaphore is destroyed. +.P +If the +.IR pshared +argument has a non-zero value, then the semaphore is shared between +processes; in this case, any process that can access the semaphore +.IR sem +can use +.IR sem +for performing +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR() +operations. +.P +If the +.IR pshared +argument is zero, then the semaphore is shared between threads of the +process; any thread in this process can use +.IR sem +for performing +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_destroy\fR() +operations. +.P +See +.IR "Section 2.9.9" ", " "Synchronization Object Copies and Alternative Mappings" +for further requirements. +.P +Attempting to initialize an already initialized semaphore results in +undefined behavior. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_init\fR() +function shall initialize the semaphore in +.IR sem +and return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_init\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR value +argument exceeds +{SEM_VALUE_MAX}. +.TP +.BR ENOSPC +A resource required to initialize the semaphore has been exhausted, or +the limit on semaphores (\c +{SEM_NSEMS_MAX}) +has been reached. +.TP +.BR EPERM +The process lacks appropriate privileges to initialize the +semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_open.3p b/upstream/archlinux/man3p/sem_open.3p new file mode 100644 index 00000000..aad38e9d --- /dev/null +++ b/upstream/archlinux/man3p/sem_open.3p @@ -0,0 +1,298 @@ +'\" et +.TH SEM_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_open +\(em initialize and open a named semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +sem_t *sem_open(const char *\fIname\fP, int \fIoflag\fP, ...); +.fi +.SH DESCRIPTION +The +\fIsem_open\fR() +function shall establish a connection between a named semaphore +and a process. Following a call to +\fIsem_open\fR() +with semaphore name +.IR name , +the process may reference the semaphore associated with +.IR name +using the address returned from the call. This semaphore may be used +in subsequent calls to +\fIsem_wait\fR(), +\fIsem_timedwait\fR(), +\fIsem_trywait\fR(), +\fIsem_post\fR(), +and +\fIsem_close\fR(). +The semaphore remains usable by this process until the semaphore is +closed by a successful call to +\fIsem_close\fR(), +\fI_exit\fR(), +or one of the +.IR exec +functions. +.P +The +.IR oflag +argument controls whether the semaphore is created or merely accessed +by the call to +\fIsem_open\fR(). +The following flag bits may be set in +.IR oflag : +.IP O_CREAT 10 +This flag is used to create a semaphore if it does not already exist. +If O_CREAT is set and the semaphore already exists, then O_CREAT has no +effect, except as noted under O_EXCL. Otherwise, +\fIsem_open\fR() +creates a named semaphore. The O_CREAT flag requires a third and a +fourth argument: +.IR mode , +which is of type +.BR mode_t , +and +.IR value , +which is of type +.BR unsigned . +The semaphore is created with an initial value of +.IR value . +Valid initial values for semaphores are less than or equal to +{SEM_VALUE_MAX}. +.RS 10 +.P +The user ID of the semaphore shall be set to the effective user ID of +the process. The group ID of the semaphore shall be set to the effective +group ID of the process; however, if the +.IR name +argument is visible in the file system, the group ID may be set to +the group ID of the containing directory. The permission bits of the +semaphore are set to the value of the +.IR mode +argument except those set in the file mode creation mask of the +process. When bits in +.IR mode +other than the file permission bits are specified, the effect is +unspecified. +.P +After the semaphore named +.IR name +has been created by +\fIsem_open\fR() +with the O_CREAT flag, other processes can connect to the semaphore by +calling +\fIsem_open\fR() +with the same value of +.IR name . +.RE +.IP O_EXCL 10 +If O_EXCL and O_CREAT are set, +\fIsem_open\fR() +fails if the semaphore +.IR name +exists. The check for the existence of the semaphore and the creation +of the semaphore if it does not exist are atomic with respect to other +processes executing +\fIsem_open\fR() +with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, +the effect is undefined. +.RS 10 +.P +If flags other than O_CREAT and O_EXCL are specified in the +.IR oflag +parameter, the effect is unspecified. +.RE +.P +The +.IR name +argument points to a string naming a semaphore object. It is +unspecified whether the name appears in the file system and is visible +to functions that take pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except +that the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as +the pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fIsem_open\fR() +with the same value of +.IR name +shall refer to the same semaphore object, as long as that name has not +been removed. If +.IR name +does not begin with the + +character, the effect is implementation-defined. +.P +If a process makes multiple successful calls to +\fIsem_open\fR() +with the same value for +.IR name , +the same semaphore address shall be returned for each such successful +call, provided that there have been no calls to +\fIsem_unlink\fR() +for this semaphore, and at least one previous successful +\fIsem_open\fR() +call for this semaphore has not been matched with a +\fIsem_close\fR() +call. +.P +References to copies of the semaphore produce undefined results. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_open\fR() +function shall return the address of the semaphore. Otherwise, it +shall return a value of SEM_FAILED and set +.IR errno +to indicate the error. The symbol SEM_FAILED is defined in the +.IR +header. No successful return from +\fIsem_open\fR() +shall return the value SEM_FAILED. +.SH ERRORS +If any of the following conditions occur, the +\fIsem_open\fR() +function shall return SEM_FAILED and set +.IR errno +to the corresponding value: +.TP +.BR EACCES +The named semaphore exists and the permissions specified by +.IR oflag +are denied, or the named semaphore does not exist and permission to +create the named semaphore is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set and the named semaphore already exists. +.TP +.BR EINTR +The +\fIsem_open\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +The +\fIsem_open\fR() +operation is not supported for the given name, or O_CREAT was specified +in +.IR oflag +and +.IR value +was greater than +{SEM_VALUE_MAX}. +.TP +.BR EMFILE +Too many semaphore descriptors or file descriptors are currently in use +by this process. +.TP +.BR ENFILE +Too many semaphores are currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and the named semaphore does not exist. +.TP +.BR ENOMEM +There is insufficient memory for the creation of the new named +semaphore. +.TP +.BR ENOSPC +There is insufficient space on a storage device for the creation of the +new named semaphore. +.P +If any of the following conditions occur, the +\fIsem_open\fR() +function may return SEM_FAILED and set +.IR errno +to the corresponding value: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Early drafts required an error return value of \-1 with the type +.BR "sem_t *" +for the +\fIsem_open\fR() +function, which is not guaranteed to be portable across +implementations. The revised text provides the symbolic error code +SEM_FAILED to eliminate the type conflict. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIsem_open\fR() +and +\fIsem_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.ad l +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_post.3p b/upstream/archlinux/man3p/sem_post.3p new file mode 100644 index 00000000..e9bd3fa5 --- /dev/null +++ b/upstream/archlinux/man3p/sem_post.3p @@ -0,0 +1,106 @@ +'\" et +.TH SEM_POST "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_post +\(em unlock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_post(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_post\fR() +function shall unlock the semaphore referenced by +.IR sem +by performing a semaphore unlock operation on that semaphore. +.P +If the semaphore value resulting from this operation is positive, then +no threads were blocked waiting for the semaphore to become unlocked; +the semaphore value is simply incremented. +.P +If the value of the semaphore resulting from this operation is zero, +then one of the threads blocked waiting for the semaphore shall be +allowed to return successfully from its call to +\fIsem_wait\fR(). +If the Process Scheduling option is supported, the thread to be +unblocked shall be chosen in a manner appropriate to the scheduling +policies and parameters in effect for the blocked threads. In the case +of the schedulers SCHED_FIFO and SCHED_RR, +the highest priority waiting thread shall be unblocked, and if there is +more than one highest priority thread blocked waiting for the +semaphore, then the highest priority thread that has been waiting the +longest shall be unblocked. If the Process Scheduling option is not +defined, the choice of a thread to unblock is unspecified. +.P +If the Process Sporadic Server option is supported, and the scheduling +policy is SCHED_SPORADIC, the semantics are as per SCHED_FIFO above. +.P +The +\fIsem_post\fR() +function shall be async-signal-safe and may be invoked from a +signal-catching function. +.SH "RETURN VALUE" +If successful, the +\fIsem_post\fR() +function shall return zero; otherwise, the function shall return \-1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_post\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +See +.IR "\fIsem_timedwait\fR\^(\|)". +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_timedwait.3p b/upstream/archlinux/man3p/sem_timedwait.3p new file mode 100644 index 00000000..3b224295 --- /dev/null +++ b/upstream/archlinux/man3p/sem_timedwait.3p @@ -0,0 +1,233 @@ +'\" et +.TH SEM_TIMEDWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_timedwait +\(em lock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int sem_timedwait(sem_t *restrict \fIsem\fP, + const struct timespec *restrict \fIabstime\fP); +.fi +.SH DESCRIPTION +The +\fIsem_timedwait\fR() +function shall lock the semaphore referenced by +.IR sem +as in the +\fIsem_wait\fR() +function. However, if the semaphore cannot be locked without waiting +for another process or thread to unlock the semaphore by performing a +\fIsem_post\fR() +function, this wait shall be terminated when the specified timeout +expires. +.P +The timeout shall expire when the absolute time specified by +.IR abstime +passes, as measured by the clock on which timeouts are based (that is, +when the value of that clock equals or exceeds +.IR abstime ), +or if the absolute time specified by +.IR abstime +has already been passed at the time of the call. +.P +The timeout shall be based on the CLOCK_REALTIME clock. +The resolution of the timeout shall be the resolution of the +clock on which it is based. The +.BR timespec +data type is defined as a structure in the +.IR +header. +.P +Under no circumstance shall the function fail with a timeout if the +semaphore can be locked immediately. The validity of the +.IR abstime +need not be checked if the semaphore can be locked immediately. +.SH "RETURN VALUE" +The +\fIsem_timedwait\fR() +function shall return zero if the calling process successfully +performed the semaphore lock operation on the semaphore designated by +.IR sem . +If the call was unsuccessful, the state of the semaphore shall be +unchanged, and the function shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_timedwait\fR() +function shall fail if: +.TP +.BR EINVAL +The process or thread would have blocked, and the +.IR abstime +parameter specified a nanoseconds field value less than zero or greater +than or equal to 1\|000 million. +.TP +.BR ETIMEDOUT +The semaphore could not be locked before the specified timeout expired. +.P +The +\fIsem_timedwait\fR() +function may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EINTR +A signal interrupted this function. +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +The program shown below operates on an unnamed semaphore. The program +expects two command-line arguments. The first argument specifies a +seconds value that is used to set an alarm timer to generate a SIGALRM +signal. This handler performs a +.IR sem_post (3) +to increment the semaphore that is being waited on in +\fImain\fR() +using +\fIsem_timedwait\fR(). +The second command-line argument specifies the length of the timeout, +in seconds, for +\fIsem_timedwait\fR(). +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +#include +#include +.P +sem_t sem; +.P +static void +handler(int sig) +{ + int sav_errno = errno; + static const char info_msg[] = "sem_post() from handler\en"; + write(STDOUT_FILENO, info_msg, sizeof info_msg - 1); + if (sem_post(&sem) == -1) { + static const char err_msg[] = "sem_post() failed\en"; + write(STDERR_FILENO, err_msg, sizeof err_msg - 1); + _exit(EXIT_FAILURE); + } + errno = sav_errno; +} +.P +int +main(int argc, char *argv[]) +{ + struct sigaction sa; + struct timespec ts; + int s; +.P + if (argc != 3) { + fprintf(stderr, "Usage: %s \en", + argv[0]); + exit(EXIT_FAILURE); + } +.P + if (sem_init(&sem, 0, 0) == -1) { + perror("sem_init"); + exit(EXIT_FAILURE); + } +.P + /* Establish SIGALRM handler; set alarm timer using argv[1] */ +.P + sa.sa_handler = handler; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + if (sigaction(SIGALRM, &sa, NULL) == -1) { + perror("sigaction"); + exit(EXIT_FAILURE); + } +.P + alarm(atoi(argv[1])); +.P + /* Calculate relative interval as current time plus + number of seconds given argv[2] */ +.P + if (clock_gettime(CLOCK_REALTIME, &ts) == -1) { + perror("clock_gettime"); + exit(EXIT_FAILURE); + } + ts.tv_sec += atoi(argv[2]); +.P + printf("main() about to call sem_timedwait()\en"); + while ((s = sem_timedwait(&sem, &ts)) == -1 && errno == EINTR) + continue; /* Restart if interrupted by handler */ +.P + /* Check what happened */ +.P + if (s == -1) { + if (errno == ETIMEDOUT) + printf("sem_timedwait() timed out\en"); + else + perror("sem_timedwait"); + } else + printf("sem_timedwait() succeeded\en"); +.P + exit((s == 0) ? EXIT_SUCCESS : EXIT_FAILURE); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority +inversion, as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_trywait.3p b/upstream/archlinux/man3p/sem_trywait.3p new file mode 100644 index 00000000..90d25e25 --- /dev/null +++ b/upstream/archlinux/man3p/sem_trywait.3p @@ -0,0 +1,129 @@ +'\" et +.TH SEM_TRYWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_trywait, +sem_wait +\(em lock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_trywait(sem_t *\fIsem\fP); +int sem_wait(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +The +\fIsem_trywait\fR() +function shall lock the semaphore referenced by +.IR sem +only if the semaphore is currently not locked; that is, if the +semaphore value is currently positive. Otherwise, it shall not lock +the semaphore. +.P +The +\fIsem_wait\fR() +function shall lock the semaphore referenced by +.IR sem +by performing a semaphore lock operation on that semaphore. If the +semaphore value is currently zero, then the calling thread shall not +return from the call to +\fIsem_wait\fR() +until it either locks the semaphore or the call is interrupted by a +signal. +.P +Upon successful return, the state of the semaphore shall be locked and +shall remain locked until the +\fIsem_post\fR() +function is executed and returns successfully. +.P +The +\fIsem_wait\fR() +function is interruptible by the delivery of a signal. +.SH "RETURN VALUE" +The +\fIsem_trywait\fR() +and +\fIsem_wait\fR() +functions shall return zero if the calling process successfully +performed the semaphore lock operation on the semaphore designated by +.IR sem . +If the call was unsuccessful, the state of the semaphore shall be +unchanged, and the function shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_trywait\fR() +function shall fail if: +.TP +.BR EAGAIN +The semaphore was already locked, so it cannot be immediately locked by +the +\fIsem_trywait\fR() +operation. +.P +The +\fIsem_trywait\fR() +and +\fIsem_wait\fR() +functions may fail if: +.TP +.BR EDEADLK +A deadlock condition was detected. +.TP +.BR EINTR +A signal interrupted this function. +.TP +.BR EINVAL +The +.IR sem +argument does not refer to a valid semaphore. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions may be subject to priority inversion, +as discussed in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion". +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.291" ", " "Priority Inversion", +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_unlink.3p b/upstream/archlinux/man3p/sem_unlink.3p new file mode 100644 index 00000000..91d9a620 --- /dev/null +++ b/upstream/archlinux/man3p/sem_unlink.3p @@ -0,0 +1,135 @@ +'\" et +.TH SEM_UNLINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_unlink +\(em remove a named semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_unlink(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIsem_unlink\fR() +function shall remove the semaphore named by the string +.IR name . +If the semaphore named by +.IR name +is currently referenced by other processes, then +\fIsem_unlink\fR() +shall have no effect on the state of the semaphore. If one or more +processes have the semaphore open when +\fIsem_unlink\fR() +is called, destruction of the semaphore is postponed until all +references to the semaphore have been destroyed by calls to +\fIsem_close\fR(), +\fI_exit\fR(), +or +.IR exec . +Calls to +\fIsem_open\fR() +to recreate or reconnect to the semaphore refer to a new semaphore +after +\fIsem_unlink\fR() +is called. The +\fIsem_unlink\fR() +call shall not block until all references have been destroyed; it +shall return immediately. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsem_unlink\fR() +function shall return a value of 0. Otherwise, the semaphore shall not +be changed and the function shall return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsem_unlink\fR() +function shall fail if: +.TP +.BR EACCES +Permission is denied to unlink the named semaphore. +.TP +.BR ENOENT +The named semaphore does not exist. +.P +The +\fIsem_unlink\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +A call to +\fIsem_unlink\fR() +with a +.IR name +argument that contains the same semaphore name as was previously used +in a successful +\fIsem_open\fR() +call shall not give an +.BR [ENAMETOOLONG] +error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIsem_open\fR() +and +\fIsem_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sem_wait.3p b/upstream/archlinux/man3p/sem_wait.3p new file mode 100644 index 00000000..e300e705 --- /dev/null +++ b/upstream/archlinux/man3p/sem_wait.3p @@ -0,0 +1,40 @@ +'\" et +.TH SEM_WAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sem_wait +\(em lock a semaphore +.SH SYNOPSIS +.LP +.nf +#include +.P +int sem_wait(sem_t *\fIsem\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsem_trywait\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/semctl.3p b/upstream/archlinux/man3p/semctl.3p new file mode 100644 index 00000000..01709cf8 --- /dev/null +++ b/upstream/archlinux/man3p/semctl.3p @@ -0,0 +1,340 @@ +'\" et +.TH SEMCTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +semctl +\(em XSI semaphore control operations +.SH SYNOPSIS +.LP +.nf +#include\ +.P +int semctl(int \fIsemid\fP, int \fIsemnum\fP, int \fIcmd\fP, ...); +.fi +.SH DESCRIPTION +The +\fIsemctl\fR() +function operates on XSI semaphores (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.17" ", " "Semaphore"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIsemctl\fR() +function provides a variety of semaphore control operations as +specified by +.IR cmd . +The fourth argument is optional and depends upon the operation +requested. If required, it is of type +.BR "union semun" , +which the application shall explicitly declare: +.sp +.RS 4 +.nf + +union semun { + int val; + struct semid_ds *buf; + unsigned short *array; +} arg; +.fi +.P +.RE +.P +Each operation shall be performed atomically. +.P +The following semaphore control operations as specified by +.IR cmd +are executed with respect to the semaphore specified by +.IR semid +and +.IR semnum . +The level of permission required for each operation is shown with each +command; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +The symbolic names for the values of +.IR cmd +are defined in the +.IR +header: +.IP GETVAL 12 +Return the value of +.IR semval ; +see +.IR . +Requires read permission. +.IP SETVAL 12 +Set the value of +.IR semval +to +.IR arg.val , +where +.IR arg +is the value of the fourth argument to +\fIsemctl\fR(). +When this command is successfully executed, the +.IR semadj +value corresponding to the specified semaphore in all processes is +cleared. Also, the +.IR sem_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +Requires alter permission; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.IP GETPID 12 +Return the value of +.IR sempid . +Requires read permission. +.IP GETNCNT 12 +Return the value of +.IR semncnt . +Requires read permission. +.IP GETZCNT 12 +Return the value of +.IR semzcnt . +Requires read permission. +.P +The following values of +.IR cmd +operate on each +.IR semval +in the set of semaphores: +.IP GETALL 12 +Return the value of +.IR semval +for each semaphore in the semaphore set and place into the array +pointed to by +.IR arg.array , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(). +Requires read permission. +.IP SETALL 12 +Set the value of +.IR semval +for each semaphore in the semaphore set according to the array pointed +to by +.IR arg.array , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(). +When this command is successfully executed, the +.IR semadj +values corresponding to each specified semaphore in all processes are +cleared. Also, the +.IR sem_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +Requires alter permission. +.br +.P +The following values of +.IR cmd +are also available: +.IP IPC_STAT 12 +Place the current value of each member of the +.BR semid_ds +data structure associated with +.IR semid +into the structure pointed to by +.IR arg.buf , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(). +The contents of this structure are defined in +.IR . +Requires read permission. +.IP IPC_SET 12 +Set the value of the following members of the +.BR semid_ds +data structure associated with +.IR semid +to the corresponding value found in the structure pointed to by +.IR arg.buf , +where +.IR arg +is the fourth argument to +\fIsemctl\fR(): +.RS 12 +.sp +.RS 4 +.nf + +sem_perm.uid +sem_perm.gid +sem_perm.mode +.fi +.P +.RE +.P +The mode bits specified in +.IR "Section 2.7.1" ", " "IPC General Description" +are copied into the corresponding bits of the +.IR sem_perm.mode +associated with +.IR semid . +The stored values of any other bits are unspecified. The +.IR sem_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +This command can only be executed by a process that has an effective +user ID equal to either that of a process with appropriate privileges +or to the value of +.IR sem_perm.cuid +or +.IR sem_perm.uid +in the +.BR semid_ds +data structure associated with +.IR semid . +.RE +.IP IPC_RMID 12 +Remove the semaphore identifier specified by +.IR semid +from the system and destroy the set of semaphores and +.BR semid_ds +data structure associated with it. This command can only be executed +by a process that has an effective user ID equal to either that of a +process with appropriate privileges or to the value of +.IR sem_perm.cuid +or +.IR sem_perm.uid +in the +.BR semid_ds +data structure associated with +.IR semid . +.SH "RETURN VALUE" +If successful, the value returned by +\fIsemctl\fR() +depends on +.IR cmd +as follows: +.IP GETVAL 12 +The value of +.IR semval . +.IP GETPID 12 +The value of +.IR sempid . +.IP GETNCNT 12 +The value of +.IR semncnt . +.IP GETZCNT 12 +The value of +.IR semzcnt . +.IP "All others" 12 +0. +.P +Otherwise, +\fIsemctl\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsemctl\fR() +function shall fail if: +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR semid +is not a valid semaphore identifier, or the value of +.IR semnum +is less than 0 or greater than or equal to +.IR sem_nsems , +or the value of +.IR cmd +is not a valid command. +.TP +.BR EPERM +The argument +.IR cmd +is equal to IPC_RMID or IPC_SET +and the effective user ID of the calling process is not equal to that +of a process with appropriate privileges and it is not equal to the +value of +.IR sem_perm.cuid +or +.IR sem_perm.uid +in the data structure associated with +.IR semid . +.TP +.BR ERANGE +The argument +.IR cmd +is equal to SETVAL or SETALL and the value to which +.IR semval +is to be set is greater than the system-imposed maximum. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Refer to +.IR "\fIsemop\fR\^(\|)". +.SH "APPLICATION USAGE" +The fourth parameter in the SYNOPSIS section is now specified as +.BR \(dq...\(dq +in order to avoid a clash with the ISO\ C standard when referring to the union +.IR semun +(as defined in Issue 3) and for backwards-compatibility. +.P +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_getvalue\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.17" ", " "Semaphore", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/semget.3p b/upstream/archlinux/man3p/semget.3p new file mode 100644 index 00000000..c608bc26 --- /dev/null +++ b/upstream/archlinux/man3p/semget.3p @@ -0,0 +1,198 @@ +'\" et +.TH SEMGET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +semget +\(em get set of XSI semaphores +.SH SYNOPSIS +.LP +.nf +#include +.P +int semget(key_t \fIkey\fP, int \fInsems\fP, int \fIsemflg\fP); +.fi +.SH DESCRIPTION +The +\fIsemget\fR() +function operates on XSI semaphores (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.17" ", " "Semaphore"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIsemget\fR() +function shall return the semaphore identifier associated with +.IR key . +.P +A semaphore identifier with its associated +.BR semid_ds +data structure and its associated set of +.IR nsems +semaphores (see +.IR ) +is created for +.IR key +if one of the following is true: +.IP " *" 4 +The argument +.IR key +is equal to IPC_PRIVATE. +.IP " *" 4 +The argument +.IR key +does not already have a semaphore identifier associated with it and +(\fIsemflg\fP &IPC_CREAT) is non-zero. +.P +Upon creation, the +.BR semid_ds +data structure associated with the new semaphore identifier is +initialized as follows: +.IP " *" 4 +In the operation permissions structure +.IR sem_perm.cuid , +.IR sem_perm.uid , +.IR sem_perm.cgid , +and +.IR sem_perm.gid +shall be set to the effective user ID and effective group ID, +respectively, of the calling process. +.IP " *" 4 +The low-order 9 bits of +.IR sem_perm.mode +shall be set to the low-order 9 bits of +.IR semflg . +.IP " *" 4 +The variable +.IR sem_nsems +shall be set to the value of +.IR nsems . +.IP " *" 4 +The variable +.IR sem_otime +shall be set to 0 and +.IR sem_ctime +shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.IP " *" 4 +The data structure associated with each semaphore in the set need not +be initialized. The +\fIsemctl\fR() +function with the command SETVAL or SETALL +can be used to initialize each semaphore. +.SH "RETURN VALUE" +Upon successful completion, +\fIsemget\fR() +shall return a non-negative integer, namely a semaphore identifier; +otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsemget\fR() +function shall fail if: +.TP +.BR EACCES +A semaphore identifier exists for +.IR key , +but operation permission as specified by the low-order 9 bits of +.IR semflg +would not be granted; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EEXIST +A semaphore identifier exists for the argument +.IR key +but ((\fIsemflg\fP &IPC_CREAT) &&(\fIsemflg\fP &IPC_EXCL)) +is non-zero. +.TP +.BR EINVAL +The value of +.IR nsems +is either less than or equal to 0 or greater than the system-imposed +limit, or a semaphore identifier exists for the argument +.IR key , +but the number of semaphores in the set associated with it is less than +.IR nsems +and +.IR nsems +is not equal to 0. +.TP +.BR ENOENT +A semaphore identifier does not exist for the argument +.IR key +and (\fIsemflg\fP &IPC_CREAT) is equal to 0. +.TP +.BR ENOSPC +A semaphore identifier is to be created but the system-imposed limit on +the maximum number of allowed semaphores system-wide would be +exceeded. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Refer to +.IR "\fIsemop\fR\^(\|)". +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version may require that the value of the +.IR semval , +.IR sempid , +.IR semncnt , +and +.IR semzcnt +members of all semaphores in a semaphore set be initialized to zero when +a call to +\fIsemget\fR() +creates a semaphore set. Many semaphore implementations already do this +and it greatly simplifies what an application must do to initialize a +semaphore set. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIftok\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemop\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_getvalue\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.17" ", " "Semaphore", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/semop.3p b/upstream/archlinux/man3p/semop.3p new file mode 100644 index 00000000..d311aa30 --- /dev/null +++ b/upstream/archlinux/man3p/semop.3p @@ -0,0 +1,482 @@ +'\" et +.TH SEMOP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +semop +\(em XSI semaphore operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int semop(int \fIsemid\fP, struct sembuf *\fIsops\fP, size_t \fInsops\fP); +.fi +.SH DESCRIPTION +The +\fIsemop\fR() +function operates on XSI semaphores (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.17" ", " "Semaphore"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIsemop\fR() +function shall perform atomically a user-defined array of semaphore +operations in array order on the set of semaphores associated with the +semaphore identifier specified by the argument +.IR semid . +.P +The argument +.IR sops +is a pointer to a user-defined array of semaphore operation +structures. The implementation shall not modify elements of this array +unless the application uses implementation-defined extensions. +.P +The argument +.IR nsops +is the number of such structures in the array. +.P +Each structure, +.BR sembuf , +includes the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +unsigned short!sem_num!Semaphore number. +short!sem_op!Semaphore operation. +short!sem_flg!Operation flags. +.TE +.P +Each semaphore operation specified by +.IR sem_op +is performed on the corresponding semaphore specified by +.IR semid +and +.IR sem_num . +.P +The variable +.IR sem_op +specifies one of three semaphore operations: +.IP " 1." 4 +If +.IR sem_op +is a negative integer and the calling process has alter permission, one +of the following shall occur: +.RS 4 +.IP " *" 4 +If +.IR semval (see +.IR ) +is greater than or equal to the absolute value of +.IR sem_op , +the absolute value of +.IR sem_op +is subtracted from +.IR semval . +Also, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the absolute value of +.IR sem_op +shall be added to the +.IR semadj +value of the calling process for the specified semaphore. +.IP " *" 4 +If +.IR semval +is less than the absolute value of +.IR sem_op +and (\fIsem_flg\fP &IPC_NOWAIT) is non-zero, +\fIsemop\fR() +shall return immediately. +.IP " *" 4 +If +.IR semval +is less than the absolute value of +.IR sem_op +and (\fIsem_flg\fP &IPC_NOWAIT) is 0, +\fIsemop\fR() +shall increment the +.IR semncnt +associated with the specified semaphore and suspend execution of the +calling thread until one of the following conditions occurs: +.RS 4 +.IP -- 4 +The value of +.IR semval +becomes greater than or equal to the absolute value of +.IR sem_op . +When this occurs, the value of +.IR semncnt +associated with the specified semaphore shall be decremented, the +absolute value of +.IR sem_op +shall be subtracted from +.IR semval +and, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the absolute value of +.IR sem_op +shall be added to the +.IR semadj +value of the calling process for the specified semaphore. +.IP -- 4 +The +.IR semid +for which the calling thread is awaiting action is removed from the +system. When this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \-1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught. When this +occurs, the value of +.IR semncnt +associated with the specified semaphore shall be decremented, and the +calling thread shall resume execution in the manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.RE +.IP " 2." 4 +If +.IR sem_op +is a positive integer and the calling process has alter permission, the +value of +.IR sem_op +shall be added to +.IR semval +and, if (\fIsem_flg\fP &SEM_UNDO) is non-zero, the value of +.IR sem_op +shall be subtracted from the +.IR semadj +value of the calling process for the specified semaphore. +.IP " 3." 4 +If +.IR sem_op +is 0 and the calling process has read permission, one of the following +shall occur: +.RS 4 +.IP " *" 4 +If +.IR semval +is 0, +\fIsemop\fR() +shall return immediately. +.IP " *" 4 +If +.IR semval +is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is non-zero, +\fIsemop\fR() +shall return immediately. +.IP " *" 4 +If +.IR semval +is non-zero and (\fIsem_flg\fP &IPC_NOWAIT) is 0, +\fIsemop\fR() +shall increment the +.IR semzcnt +associated with the specified semaphore and suspend execution of the +calling thread until one of the following occurs: +.RS 4 +.IP -- 4 +The value of +.IR semval +becomes 0, at which time the value of +.IR semzcnt +associated with the specified semaphore shall be decremented. +.IP -- 4 +The +.IR semid +for which the calling thread is awaiting action is removed from the +system. When this occurs, +.IR errno +shall be set to +.BR [EIDRM] +and \-1 shall be returned. +.IP -- 4 +The calling thread receives a signal that is to be caught. When this +occurs, the value of +.IR semzcnt +associated with the specified semaphore shall be decremented, and the +calling thread shall resume execution in the manner prescribed in +.IR "\fIsigaction\fR\^(\|)". +.RE +.RE +.P +Upon successful completion, the value of +.IR sempid +for each semaphore specified in the array pointed to by +.IR sops +shall be set to the process ID of the calling process. Also, the +.IR sem_otime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.SH "RETURN VALUE" +Upon successful completion, +\fIsemop\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsemop\fR() +function shall fail if: +.TP +.BR E2BIG +The value of +.IR nsops +is greater than the system-imposed maximum. +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EAGAIN +The operation would result in suspension of the calling process but +(\fIsem_flg\fP &IPC_NOWAIT) is non-zero. +.TP +.BR EFBIG +The value of +.IR sem_num +is greater than or equal to the number of semaphores in the set +associated with +.IR semid . +.TP +.BR EIDRM +The semaphore identifier +.IR semid +is removed from the system. +.TP +.BR EINTR +The +\fIsemop\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +The value of +.IR semid +is not a valid semaphore identifier, or the number of individual +semaphores for which the calling process requests a SEM_UNDO would +exceed the system-imposed limit. +.TP +.BR ENOSPC +The limit on the number of individual processes requesting a SEM_UNDO +would be exceeded. +.TP +.BR ERANGE +An operation would cause a +.IR semval +to overflow the system-imposed limit, or an operation would cause a +.IR semadj +value to overflow the system-imposed limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting Values in Semaphores" +.P +The following example sets the values of the two semaphores associated +with the +.IR semid +identifier to the values contained in the +.IR sb +array. +.sp +.RS 4 +.nf + +#include +\&... +int semid; +struct sembuf sb[2]; +int nsops = 2; +int result; +.P +/* Code to initialize semid. */ +\&... +.P +/* Adjust value of semaphore in the semaphore array semid. */ +sb[0].sem_num = 0; +sb[0].sem_op = -1; +sb[0].sem_flg = SEM_UNDO | IPC_NOWAIT; +sb[1].sem_num = 1; +sb[1].sem_op = 1; +sb[1].sem_flg = 0; +.P +result = semop(semid, sb, nsops); +.fi +.P +.RE +.SS "Creating a Semaphore Identifier" +.P +The following example gets a unique semaphore key using the +\fIftok\fR() +function, then gets a semaphore ID associated with that key using the +\fIsemget\fR() +function (the first call also tests to make sure the semaphore exists). +If the semaphore does not exist, the program creates it, as shown by +the second call to +\fIsemget\fR(). +In creating the semaphore for the queuing process, the program +attempts to create one semaphore with read/write permission for all. It +also uses the IPC_EXCL flag, which forces +\fIsemget\fR() +to fail if the semaphore already exists. +.P +After creating the semaphore, the program uses calls to +\fIsemctl\fR() +and +\fIsemop\fR() +to initialize it to the values in the +.IR sbuf +array. The number of processes that can execute concurrently without +queuing is initially set to 2. The final call to +\fIsemget\fR() +creates a semaphore identifier that can be used later in the program. +.P +Processes that obtain +.IR semid +without creating it check that +.IR sem_otime +is non-zero, to ensure that the creating process has completed the +\fIsemop\fR() +initialization. +.P +The final call to +\fIsemop\fR() +acquires the semaphore and waits until it is free; the SEM_UNDO option +releases the semaphore when the process exits, waiting until there are +less than two processes running concurrently. +.br +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +\&... +key_t semkey; +int semid; +struct sembuf sbuf; +union semun { + int val; + struct semid_ds *buf; + unsigned short *array; +} arg; +struct semid_ds ds; +\&... +/* Get unique key for semaphore. */ +if ((semkey = ftok("/tmp", \(aqa\(aq)) == (key_t) -1) { + perror("IPC error: ftok"); exit(1); +} +.P +/* Get semaphore ID associated with this key. */ +if ((semid = semget(semkey, 0, 0)) == -1) { +.P + /* Semaphore does not exist - Create. */ + if ((semid = semget(semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | + S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) + { + /* Initialize the semaphore. */ + arg.val = 0; + sbuf.sem_num = 0; + sbuf.sem_op = 2; /* This is the number of runs without queuing. */ + sbuf.sem_flg = 0; + if (semctl(semid, 0, SETVAL, arg) == -1 + || semop(semid, &sbuf, 1) == -1) { + perror("IPC error: semop"); exit(1); + } + } + else if (errno == EEXIST) { + if ((semid = semget(semkey, 0, 0)) == -1) { + perror("IPC error 1: semget"); exit(1); + } + goto check_init; + } + else { + perror("IPC error 2: semget"); exit(1); + } +} +else +{ + /* Check that semid has completed initialization. */ + /* An application can use a retry loop at this point rather than + exiting. */ + check_init: + arg.buf = &ds; + if (semctl(semid, 0, IPC_STAT, arg) < 0) { + perror("IPC error 3: semctl"); exit(1); + } + if (ds.sem_otime == 0) { + perror("IPC error 4: semctl"); exit(1); + } +} +\&... +sbuf.sem_num = 0; +sbuf.sem_op = -1; +sbuf.sem_flg = SEM_UNDO; +if (semop(semid, &sbuf, 1) == -1) { + perror("IPC Error: semop"); exit(1); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIsemctl\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsem_close\fR\^(\|)", +.IR "\fIsem_destroy\fR\^(\|)", +.IR "\fIsem_getvalue\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsem_post\fR\^(\|)", +.IR "\fIsem_trywait\fR\^(\|)", +.IR "\fIsem_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.17" ", " "Semaphore", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/send.3p b/upstream/archlinux/man3p/send.3p new file mode 100644 index 00000000..d798413a --- /dev/null +++ b/upstream/archlinux/man3p/send.3p @@ -0,0 +1,226 @@ +'\" et +.TH SEND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +send +\(em send a message on a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t send(int \fIsocket\fP, const void *\fIbuffer\fP, size_t \fIlength\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIsend\fR() +function shall initiate transmission of a message from the specified +socket to its peer. The +\fIsend\fR() +function shall send a message only when the socket is connected. If +the socket is a connectionless-mode socket, the message shall be sent +to the pre-specified peer address. +.P +The +\fIsend\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fIbuffer\fR" 12 +Points to the buffer containing the message to send. +.IP "\fIlength\fR" 12 +Specifies the length of the message in bytes. +.IP "\fIflags\fR" 12 +Specifies the type of message transmission. Values of this argument are +formed by logically OR'ing zero or more of the following flags: +.RS 12 +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Sends out-of-band data on sockets that support out-of-band +communications. The significance and semantics of out-of-band data are +protocol-specific. +.IP MSG_NOSIGNAL 14 +Requests not to send the SIGPIPE signal if an attempt to send is made +on a stream-oriented socket that is no longer connected. The +.BR [EPIPE] +error shall still be returned. +.RE +.P +The length of the message to be sent is specified by the +.IR length +argument. If the message is too long to pass through the underlying +protocol, +\fIsend\fR() +shall fail and no data shall be transmitted. +.P +Successful completion of a call to +\fIsend\fR() +does not guarantee delivery of the message. A return value of \-1 +indicates only locally-detected errors. +.P +If space is not available at the sending socket to hold the message to +be transmitted, and the socket file descriptor does not have O_NONBLOCK +set, +\fIsend\fR() +shall block until space is available. If space is not available at the +sending socket to hold the message to be transmitted, and the socket +file descriptor does have O_NONBLOCK set, +\fIsend\fR() +shall fail. The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when it is possible to send more +data. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIsend\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIsend\fR() +shall return the number of bytes sent. Otherwise, \-1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsend\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EDESTADDRREQ +.br +The socket is not connection-mode and no peer address is set. +.TP +.BR EINTR +A signal interrupted +\fIsend\fR() +before any data was transmitted. +.TP +.BR EMSGSIZE +The message is too large to be sent all at once, as the socket requires. +.TP +.BR ENOTCONN +The socket is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The +.IR socket +argument is associated with a socket that does not support one or more +of the values set in +.IR flags . +.TP +.BR EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if the socket is of +type SOCK_STREAM or SOCK_SEQPACKET and the MSG_NOSIGNAL flag is not set, +the SIGPIPE signal is generated to the calling thread. +.P +The +\fIsend\fR() +function may fail if: +.TP +.BR EACCES +The calling process does not have appropriate privileges. +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +If the +.IR socket +argument refers to a connection-mode socket, the +\fIsend\fR() +function is equivalent to +\fIsendto\fR() +(with any value for the +.IR dest_addr +and +.IR dest_len +arguments, as they are ignored in this case). If the +.IR socket +argument refers to a socket and the +.IR flags +argument is 0, the +\fIsend\fR() +function is equivalent to +\fIwrite\fR(). +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sendmsg.3p b/upstream/archlinux/man3p/sendmsg.3p new file mode 100644 index 00000000..b39a7aec --- /dev/null +++ b/upstream/archlinux/man3p/sendmsg.3p @@ -0,0 +1,325 @@ +'\" et +.TH SENDMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sendmsg +\(em send a message on a socket using a message structure +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t sendmsg(int \fIsocket\fP, const struct msghdr *\fImessage\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +\fIsendmsg\fR() +function shall send a message through a connection-mode or +connectionless-mode socket. If the socket is a connectionless-mode +socket, the message shall be sent to the address specified by +.BR msghdr +if no pre-specified peer address has been set. If a peer address has +been pre-specified, either the message shall be sent to the address +specified in +.BR msghdr +(overriding the pre-specified peer address), or the function shall +return \-1 and set +.IR errno +to +.BR [EISCONN] . +If the socket is connection-mode, the destination address in +.BR msghdr +shall be ignored. +.P +The +\fIsendmsg\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fImessage\fR" 12 +Points to a +.BR msghdr +structure, containing both the destination address and the buffers for +the outgoing message. The length and format of the address depend on +the address family of the socket. The +.IR msg_flags +member is ignored. +.IP "\fIflags\fR" 12 +Specifies the type of message transmission. The application may +specify 0 or the following flag: +.RS 12 +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Sends out-of-band data on sockets that support out-of-bound data. The +significance and semantics of out-of-band data are protocol-specific. +.IP MSG_NOSIGNAL 14 +Requests not to send the SIGPIPE signal if an attempt to send is made +on a stream-oriented socket that is no longer connected. The +.BR [EPIPE] +error shall still be returned. +.RE +.P +The +.IR msg_iov +and +.IR msg_iovlen +fields of +.IR message +specify zero or more buffers containing the data to be sent. +.IR msg_iov +points to an array of +.BR iovec +structures; +.IR msg_iovlen +shall be set to the dimension of this array. In each +.BR iovec +structure, the +.IR iov_base +field specifies a storage area and the +.IR iov_len +field gives its size in bytes. Some of these sizes can be zero. The +data from each storage area indicated by +.IR msg_iov +is sent in turn. +.P +Successful completion of a call to +\fIsendmsg\fR() +does not guarantee delivery of the message. A return value of \-1 +indicates only locally-detected errors. +.P +If space is not available at the sending socket to hold the message to +be transmitted and the socket file descriptor does not have O_NONBLOCK +set, the +\fIsendmsg\fR() +function shall block until space is available. If space is not +available at the sending socket to hold the message to be transmitted +and the socket file descriptor does have O_NONBLOCK set, the +\fIsendmsg\fR() +function shall fail. +.P +If the socket protocol supports broadcast and the specified address is +a broadcast address for the socket protocol, +\fIsendmsg\fR() +shall fail if the SO_BROADCAST option is not set for the socket. +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIsendmsg\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIsendmsg\fR() +shall return the number of bytes sent. Otherwise, \-1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsendmsg\fR() +function shall fail if: +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP +.BR EAFNOSUPPORT +.br +Addresses in the specified address family cannot be used with this +socket. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +A signal interrupted +\fIsendmsg\fR() +before any data was transmitted. +.TP +.BR EINVAL +The sum of the +.IR iov_len +values overflows an +.BR ssize_t . +.TP +.BR EMSGSIZE +The message is too large to be sent all at once (as the socket +requires), or the +.IR msg_iovlen +member of the +.BR msghdr +structure pointed to by +.IR message +is less than or equal to 0 or is greater than +{IOV_MAX}. +.TP +.BR ENOTCONN +The socket is connection-mode but is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The +.IR socket +argument is associated with a socket that does not support one or more +of the values set in +.IR flags . +.TP +.BR EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if the socket is of +type SOCK_STREAM or SOCK_SEQPACKET and the MSG_NOSIGNAL flag is not set, +the SIGPIPE signal is generated to the calling thread. +.P +If the address family of the socket is AF_UNIX, then +\fIsendmsg\fR() +shall fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the pathname does not name an existing file or the path +name is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in the socket address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in the socket address contains at least +one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIsendmsg\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP +.BR EDESTADDRREQ +.br +The socket is not connection-mode and does not have its peer address +set, and no destination address was specified. +.TP +.BR EHOSTUNREACH +.br +The destination host cannot be reached (probably because the host is +down or a remote router cannot reach it). +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file system. +.TP +.BR EISCONN +A destination address was specified and the socket is already +connected. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.P +If the address family of the socket is AF_UNIX, then +\fIsendmsg\fR() +may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +Done. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when it is possible to send more +data. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sendto.3p b/upstream/archlinux/man3p/sendto.3p new file mode 100644 index 00000000..4c0340dd --- /dev/null +++ b/upstream/archlinux/man3p/sendto.3p @@ -0,0 +1,316 @@ +'\" et +.TH SENDTO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sendto +\(em send a message on a socket +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t sendto(int \fIsocket\fP, const void *\fImessage\fP, size_t \fIlength\fP, + int \fIflags\fP, const struct sockaddr *\fIdest_addr\fP, + socklen_t \fIdest_len\fP); +.fi +.SH DESCRIPTION +The +\fIsendto\fR() +function shall send a message through a connection-mode or +connectionless-mode socket. +.P +If the socket is a connectionless-mode socket, the message shall be sent +to the address specified by +.IR dest_addr +if no pre-specified peer address has been set. If a peer address has +been pre-specified, either the message shall be sent to the address +specified by +.IR dest_addr +(overriding the pre-specified peer address), or the function shall +return \-1 and set +.IR errno +to +.BR [EISCONN] . +.P +If the socket is connection-mode, +.IR dest_addr +shall be ignored. +.P +The +\fIsendto\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the socket file descriptor. +.IP "\fImessage\fR" 12 +Points to a buffer containing the message to be sent. +.IP "\fIlength\fR" 12 +Specifies the size of the message in bytes. +.IP "\fIflags\fR" 12 +Specifies the type of message transmission. Values of this argument +are formed by logically OR'ing zero or more of the following flags: +.RS 12 +.IP MSG_EOR 14 +Terminates a record (if supported by the protocol). +.IP MSG_OOB 14 +Sends out-of-band data on sockets that support out-of-band data. The +significance and semantics of out-of-band data are protocol-specific. +.IP MSG_NOSIGNAL 14 +Requests not to send the SIGPIPE signal if an attempt to send is made +on a stream-oriented socket that is no longer connected. The +.BR [EPIPE] +error shall still be returned. +.RE +.IP "\fIdest_addr\fR" 12 +Points to a +.BR sockaddr +structure containing the destination address. The length and format of +the address depend on the address family of the socket. +.IP "\fIdest_len\fR" 12 +Specifies the length of the +.BR sockaddr +structure pointed to by the +.IR dest_addr +argument. +.P +If the socket protocol supports broadcast and the specified address is +a broadcast address for the socket protocol, +\fIsendto\fR() +shall fail if the SO_BROADCAST option is not set for the socket. +.P +The +.IR dest_addr +argument specifies the address of the target. +.P +The +.IR length +argument specifies the length of the message. +.P +Successful completion of a call to +\fIsendto\fR() +does not guarantee delivery of the message. A return value of \-1 +indicates only locally-detected errors. +.P +If space is not available at the sending socket to hold the message to +be transmitted and the socket file descriptor does not have O_NONBLOCK +set, +\fIsendto\fR() +shall block until space is available. If space is not available at the +sending socket to hold the message to be transmitted and the socket +file descriptor does have O_NONBLOCK set, +\fIsendto\fR() +shall fail. +.br +.P +The socket in use may require the process to have appropriate +privileges to use the +\fIsendto\fR() +function. +.SH "RETURN VALUE" +Upon successful completion, +\fIsendto\fR() +shall return the number of bytes sent. Otherwise, \-1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsendto\fR() +function shall fail if: +.TP +.BR EAFNOSUPPORT +.br +Addresses in the specified address family cannot be used with this +socket. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The socket's file descriptor is marked O_NONBLOCK and the requested +operation would block. +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR ECONNRESET +A connection was forcibly closed by a peer. +.TP +.BR EINTR +A signal interrupted +\fIsendto\fR() +before any data was transmitted. +.TP +.BR EMSGSIZE +The message is too large to be sent all at once, as the socket +requires. +.TP +.BR ENOTCONN +The socket is connection-mode but is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.TP +.BR EOPNOTSUPP +The +.IR socket +argument is associated with a socket that does not support one or more +of the values set in +.IR flags . +.TP +.BR EPIPE +The socket is shut down for writing, or the socket is connection-mode +and is no longer connected. In the latter case, and if the socket is of +type SOCK_STREAM or SOCK_SEQPACKET and the MSG_NOSIGNAL flag is not set, +the SIGPIPE signal is generated to the calling thread. +.P +If the address family of the socket is AF_UNIX, then +\fIsendto\fR() +shall fail if: +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +pathname in the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of the pathname does not name an existing file or the +pathname is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix of the pathname in the socket address +names an existing file that is neither a directory nor a symbolic link +to a directory, or the pathname in the socket address contains at +least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file that +is neither a directory nor a symbolic link to a directory. +.br +.P +The +\fIsendto\fR() +function may fail if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix; or +write access to the named socket is denied. +.TP +.BR EDESTADDRREQ +.br +The socket is not connection-mode and does not have its peer address +set, and no destination address was specified. +.TP +.BR EHOSTUNREACH +.br +The destination host cannot be reached (probably because the host is +down or a remote router cannot reach it). +.TP +.BR EINVAL +The +.IR dest_len +argument is not a valid length for the address family. +.TP +.BR EIO +An I/O error occurred while reading from or writing to the file +system. +.TP +.BR EISCONN +A destination address was specified and the socket is already +connected. +.TP +.BR ENETDOWN +The local network interface used to reach the destination is down. +.TP +.BR ENETUNREACH +.br +No route to the network is present. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.P +If the address family of the socket is AF_UNIX, then +\fIsendto\fR() +may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the pathname in +the socket address. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIselect\fR() +and +\fIpoll\fR() +functions can be used to determine when it is possible to send more +data. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpoll\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setbuf.3p b/upstream/archlinux/man3p/setbuf.3p new file mode 100644 index 00000000..a6c6912f --- /dev/null +++ b/upstream/archlinux/man3p/setbuf.3p @@ -0,0 +1,123 @@ +'\" et +.TH SETBUF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setbuf +\(em assign buffering to a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +void setbuf(FILE *restrict \fIstream\fP, char *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +Except that it returns no value, the function call: +.sp +.RS 4 +.nf + +setbuf(stream, buf) +.fi +.P +.RE +.P +shall be equivalent to: +.sp +.RS 4 +.nf + +setvbuf(stream, buf, _IOFBF, BUFSIZ) +.fi +.P +.RE +.P +if +.IR buf +is not a null pointer, or to: +.sp +.RS 4 +.nf + +setvbuf(stream, buf, _IONBF, BUFSIZ) +.fi +.P +.RE +.P +if +.IR buf +is a null pointer. +.SH "RETURN VALUE" +The +\fIsetbuf\fR() +function shall not return a value. +.SH ERRORS +Although the +\fIsetvbuf\fR() +interface may set +.IR errno +in defined ways, the value of +.IR errno +after a call to +\fIsetbuf\fR() +is unspecified. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +A common source of error is allocating buffer space as an ``automatic'' +variable in a code block, and then failing to close the stream in the +same block. +.P +With +\fIsetbuf\fR(), +allocating a buffer of BUFSIZ bytes does not necessarily imply that all +of BUFSIZ bytes are used for the buffer area. +.P +Since +.IR errno +is not required to be unchanged on success, in order to correctly detect +and possibly recover from errors, applications should use +\fIsetvbuf\fR() +instead of +\fIsetbuf\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIsetvbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setegid.3p b/upstream/archlinux/man3p/setegid.3p new file mode 100644 index 00000000..05a6a21b --- /dev/null +++ b/upstream/archlinux/man3p/setegid.3p @@ -0,0 +1,96 @@ +'\" et +.TH SETEGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setegid +\(em set the effective group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int setegid(gid_t \fIgid\fP); +.fi +.SH DESCRIPTION +If +.IR gid +is equal to the real group ID or the saved set-group-ID, or if the +process has appropriate privileges, +\fIsetegid\fR() +shall set the effective group ID of the calling process to +.IR gid ; +the real group ID, saved set-group-ID, and any supplementary group IDs +shall remain unchanged. +.P +The +\fIsetegid\fR() +function shall not affect the supplementary group list in any way. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \-1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetegid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR gid +argument is invalid and is not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR gid +does not match the real group ID or the saved set-group-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetuid\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setenv.3p b/upstream/archlinux/man3p/setenv.3p new file mode 100644 index 00000000..2a098e8e --- /dev/null +++ b/upstream/archlinux/man3p/setenv.3p @@ -0,0 +1,169 @@ +'\" et +.TH SETENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setenv +\(em add or change environment variable +.SH SYNOPSIS +.LP +.nf +#include +.P +int setenv(const char *\fIenvname\fP, const char *\fIenvval\fP, int \fIoverwrite\fP); +.fi +.SH DESCRIPTION +The +\fIsetenv\fR() +function shall update or add a variable in the environment of the +calling process. The +.IR envname +argument points to a string containing the name of an environment +variable to be added or altered. The environment variable shall be set +to the value to which +.IR envval +points. The function shall fail if +.IR envname +points to a string which contains an +.BR '=' +character. If the environment variable named by +.IR envname +already exists and the value of +.IR overwrite +is non-zero, the function shall return success and the environment +shall be updated. If the environment variable named by +.IR envname +already exists and the value of +.IR overwrite +is zero, the function shall return success and the environment shall +remain unchanged. +.P +The +\fIsetenv\fR() +function shall update the list of pointers to which +.IR environ +points. +.P +The strings described by +.IR envname +and +.IR envval +are copied by this function. +.P +The +\fIsetenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, zero shall be returned. Otherwise, \-1 +shall be returned, +.IR errno +set to indicate the error, and the environment shall be unchanged. +.SH ERRORS +The +\fIsetenv\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR envname +argument points to an empty string or points to a string containing an +.BR '=' +character. +.TP +.BR ENOMEM +Insufficient memory was available to add a variable or its value to the +environment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +See +\fIexec\fR() +for restrictions on changing the environment in multi-threaded +applications. +.SH RATIONALE +Unanticipated results may occur if +\fIsetenv\fR() +changes the external variable +.IR environ . +In particular, if the optional +.IR envp +argument to +\fImain\fR() +is present, it is not changed, and thus may point to an obsolete copy +of the environment (as may any other copy of +.IR environ ). +However, other than the aforementioned restriction, the standard +developers intended that the traditional method of walking through +the environment by way of the +.IR environ +pointer must be supported. +.P +It was decided that +\fIsetenv\fR() +should be required by this version because it addresses a piece of +missing functionality, and does not impose a significant burden on the +implementor. +.P +There was considerable debate as to whether the System V +\fIputenv\fR() +function or the BSD +\fIsetenv\fR() +function should be required as a mandatory function. The +\fIsetenv\fR() +function was chosen because it permitted the implementation of the +\fIunsetenv\fR() +function to delete environmental variables, without specifying an +additional interface. The +\fIputenv\fR() +function is available as part of the XSI option. +.P +The standard developers considered requiring that +\fIsetenv\fR() +indicate an error when a call to it would result in exceeding +{ARG_MAX}. +The requirement was rejected since the condition might be temporary, +with the application eventually reducing the environment size. The +ultimate success or failure depends on the size at the time of a call +to +.IR exec , +which returns an indication of this error condition. +.P +See also the RATIONALE section in +.IR "\fIgetenv\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIputenv\fR\^(\|)", +.IR "\fIunsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/seteuid.3p b/upstream/archlinux/man3p/seteuid.3p new file mode 100644 index 00000000..6738cfa9 --- /dev/null +++ b/upstream/archlinux/man3p/seteuid.3p @@ -0,0 +1,95 @@ +'\" et +.TH SETEUID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +seteuid +\(em set effective user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int seteuid(uid_t \fIuid\fP); +.fi +.SH DESCRIPTION +If +.IR uid +is equal to the real user ID or the saved set-user-ID, or if the +process has appropriate privileges, +\fIseteuid\fR() +shall set the effective user ID of the calling process to +.IR uid ; +the real user ID and saved set-user-ID shall remain unchanged. +.P +The +\fIseteuid\fR() +function shall not affect the supplementary group list in any way. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned; otherwise, \-1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIseteuid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR uid +argument is invalid and is not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR uid +does not match the real user ID or the saved set-user-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetuid\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setgid.3p b/upstream/archlinux/man3p/setgid.3p new file mode 100644 index 00000000..56541251 --- /dev/null +++ b/upstream/archlinux/man3p/setgid.3p @@ -0,0 +1,103 @@ +'\" et +.TH SETGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setgid +\(em set-group-ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int setgid(gid_t \fIgid\fP); +.fi +.SH DESCRIPTION +If the process has appropriate privileges, +\fIsetgid\fR() +shall set the real group ID, effective group ID, and the saved +set-group-ID of the calling process to +.IR gid . +.P +If the process does not have appropriate privileges, but +.IR gid +is equal to the real group ID or the saved set-group-ID, +\fIsetgid\fR() +shall set the effective group ID to +.IR gid ; +the real group ID and saved set-group-ID shall remain unchanged. +.P +The +\fIsetgid\fR() +function shall not affect the supplementary group list in any way. +.P +Any supplementary group IDs of the calling process shall remain +unchanged. +.SH "RETURN VALUE" +Upon successful completion, 0 is returned. Otherwise, \-1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetgid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR gid +argument is invalid and is not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR gid +does not match the real group ID or the saved set-group-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetuid\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setgrent.3p b/upstream/archlinux/man3p/setgrent.3p new file mode 100644 index 00000000..fe168869 --- /dev/null +++ b/upstream/archlinux/man3p/setgrent.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETGRENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setgrent +\(em reset the group database to the first entry +.SH SYNOPSIS +.LP +.nf +#include +.P +void setgrent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendgrent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sethostent.3p b/upstream/archlinux/man3p/sethostent.3p new file mode 100644 index 00000000..1d78eea4 --- /dev/null +++ b/upstream/archlinux/man3p/sethostent.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETHOSTENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sethostent +\(em network host database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void sethostent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendhostent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setitimer.3p b/upstream/archlinux/man3p/setitimer.3p new file mode 100644 index 00000000..7493f05c --- /dev/null +++ b/upstream/archlinux/man3p/setitimer.3p @@ -0,0 +1,41 @@ +'\" et +.TH SETITIMER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setitimer +\(em set the value of an interval timer +.SH SYNOPSIS +.LP +.nf +#include +.P +int setitimer(int \fIwhich\fP, const struct itimerval *restrict \fIvalue\fP, + struct itimerval *restrict \fIovalue\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetitimer\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setjmp.3p b/upstream/archlinux/man3p/setjmp.3p new file mode 100644 index 00000000..b824340b --- /dev/null +++ b/upstream/archlinux/man3p/setjmp.3p @@ -0,0 +1,106 @@ +'\" et +.TH SETJMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setjmp +\(em set jump point for a non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +int setjmp(jmp_buf \fIenv\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +A call to +\fIsetjmp\fR() +shall save the calling environment in its +.IR env +argument for later use by +\fIlongjmp\fR(). +.P +It is unspecified whether +\fIsetjmp\fR() +is a macro or a function. If a macro definition is suppressed in order +to access an actual function, or a program defines an external +identifier with the name +.IR setjmp , +the behavior is undefined. +.P +An application shall ensure that an invocation of +\fIsetjmp\fR() +appears in one of the following contexts only: +.IP " *" 4 +The entire controlling expression of a selection or iteration +statement +.IP " *" 4 +One operand of a relational or equality operator with the other operand +an integral constant expression, with the resulting expression being +the entire controlling expression of a selection or iteration statement +.IP " *" 4 +The operand of a unary +.BR '!' +operator with the resulting expression being the entire controlling +expression of a selection or iteration +.IP " *" 4 +The entire expression of an expression statement (possibly cast to +.BR void ) +.P +If the invocation appears in any other context, the behavior is +undefined. +.SH "RETURN VALUE" +If the return is from a direct invocation, +\fIsetjmp\fR() +shall return 0. If the return is from a call to +\fIlongjmp\fR(), +\fIsetjmp\fR() +shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +In general, +\fIsigsetjmp\fR() +is more useful in dealing with errors and interrupts encountered in a +low-level subroutine of a program. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setkey.3p b/upstream/archlinux/man3p/setkey.3p new file mode 100644 index 00000000..cf77ffa5 --- /dev/null +++ b/upstream/archlinux/man3p/setkey.3p @@ -0,0 +1,101 @@ +'\" et +.TH SETKEY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setkey +\(em set encoding key +(\fBCRYPT\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +void setkey(const char *\fIkey\fP); +.fi +.SH DESCRIPTION +The +\fIsetkey\fR() +function provides access to an implementation-defined encoding +algorithm. The argument of +\fIsetkey\fR() +is an array of length 64 bytes containing only the bytes with numerical +value of 0 and 1. If this string is divided into groups of 8, the +low-order bit in each group is ignored; this gives a 56-bit key which +is used by the algorithm. This is the key that shall be used with the +algorithm to encode a string +.IR block +passed to +\fIencrypt\fR(). +.P +The +\fIsetkey\fR() +function shall not change the setting of +.IR errno +if successful. An application wishing to check for error situations +should set +.IR errno +to 0 before calling +\fIsetkey\fR(). +If +.IR errno +is non-zero on return, an error has occurred. +.P +The +\fIsetkey\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +No values are returned. +.SH ERRORS +The +\fIsetkey\fR() +function shall fail if: +.TP +.BR ENOSYS +The functionality is not supported on this implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Decoding need not be implemented in all environments. This is related +to government restrictions in some countries on encryption and +decryption routines. Historical practice has been to ship a different +version of the encryption library without the decryption feature in the +routines supplied. Thus the exported version of +\fIencrypt\fR() +does encoding but not decoding. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version of the standard may mark this interface as obsolete +or remove it altogether. +.SH "SEE ALSO" +.IR "\fIcrypt\fR\^(\|)", +.IR "\fIencrypt\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setlocale.3p b/upstream/archlinux/man3p/setlocale.3p new file mode 100644 index 00000000..fd25d7ec --- /dev/null +++ b/upstream/archlinux/man3p/setlocale.3p @@ -0,0 +1,449 @@ +'\" et +.TH SETLOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setlocale +\(em set program locale +.SH SYNOPSIS +.LP +.nf +#include +.P +char *setlocale(int \fIcategory\fP, const char *\fIlocale\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIsetlocale\fR() +function selects the appropriate piece of the global locale, as specified +by the +.IR category +and +.IR locale +arguments, and can be used to change or query the entire global locale +or portions thereof. The value LC_ALL for +.IR category +names the entire global locale; other values for +.IR category +name only a part of the global locale: +.IP LC_COLLATE 12 +Affects the behavior of regular expressions and the collation +functions. +.IP LC_CTYPE 12 +Affects the behavior of regular expressions, character classification, +character conversion functions, and wide-character functions. +.IP LC_MESSAGES 12 +Affects the affirmative and negative response expressions returned by +\fInl_langinfo\fR() +and the way message catalogs are located. It may also affect the +behavior of functions that return or write message strings. +.IP LC_MONETARY 12 +Affects the behavior of functions that handle monetary values. +.IP LC_NUMERIC 12 +Affects the behavior of functions that handle numeric values. +.IP LC_TIME 12 +Affects the behavior of the time conversion functions. +.P +The +.IR locale +argument is a pointer to a character string containing the required +setting of +.IR category . +The contents of this string are implementation-defined. In addition, +the following preset values of +.IR locale +are defined for all settings of +.IR category : +.IP "\&\(dqPOSIX\(dq" 12 +Specifies the minimal environment for C-language translation called the +POSIX locale. The POSIX locale is the default global locale at entry to +\fImain\fR(). +.IP "\&\(dqC\(dq" 12 +Equivalent to +.BR \(dqPOSIX\(dq . +.IP "\&\(dq\|\(dq" 12 +Specifies an implementation-defined native environment. +The determination of the name of the new locale for the specified +category depends on the value of the associated environment +variables, +.IR LC_* +and +.IR LANG ; +see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale" +and +.IR "Chapter 8" ", " "Environment Variables". +.IP "A\ null\ pointer" 12 +Directs +\fIsetlocale\fR() +to query the current global locale setting and return the name +of the locale if +.IR category +is not LC_ALL, or a string which encodes the locale name(s) for all of +the individual categories if +.IR category +is LC_ALL. +.P +Setting all of the categories of the global locale is similar to +successively setting each individual category of the global locale, except +that all error checking is done before any actions are performed. To +set all the categories of the global locale, +\fIsetlocale\fR() +can be invoked as: +.sp +.RS 4 +.nf + +setlocale(LC_ALL, ""); +.fi +.P +.RE +.P +In this case, +\fIsetlocale\fR() +shall first verify that the values of all the environment variables it +needs according to the precedence rules (described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables") +indicate supported locales. If the value of any of these environment +variable searches yields a locale that is not supported (and non-null), +\fIsetlocale\fR() +shall return a null pointer and the global locale shall not be changed. If +all environment variables name supported locales, +\fIsetlocale\fR() +shall proceed as if it had been called for each category, using the +appropriate value from the associated environment variable or from the +implementation-defined default if there is no such value. +.P +The global locale established using +\fIsetlocale\fR() +shall only be used in threads for which no current locale has been +set using +\fIuselocale\fR() +or whose current locale has been set to the global locale using +.IR uselocale (LC_GLOBAL_LOCALE) . +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 calls +\fIsetlocale\fR(). +.P +The +\fIsetlocale\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIsetlocale\fR() +shall return the string associated with the specified category for the +new locale. Otherwise, +\fIsetlocale\fR() +shall return a null pointer and the global locale shall not be changed. +.P +A null pointer for +.IR locale +shall cause +\fIsetlocale\fR() +to return a pointer to the string associated with the specified +.IR category +for the current global locale. The global locale shall not be changed. +.P +The string returned by +\fIsetlocale\fR() +is such that a subsequent call with that string and its associated +.IR category +shall restore that part of the global locale. The application shall +not modify the string returned. +The returned string pointer might be invalidated or +the string content might be overwritten by a subsequent call to +\fIsetlocale\fR(). +The returned pointer might also be invalidated if the calling +thread is terminated. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The following code illustrates how a program can initialize the +international environment for one language, while selectively modifying +the global locale such that regular expressions and string operations +can be applied to text recorded in a different language: +.sp +.RS 4 +.nf + +setlocale(LC_ALL, "De"); +setlocale(LC_COLLATE, "Fr@dict"); +.fi +.P +.RE +.P +Internationalized programs can initiate language operation according +to environment variable settings (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables") +by calling +\fIsetlocale\fR() +as follows: +.sp +.RS 4 +.nf + +setlocale(LC_ALL, ""); +.fi +.P +.RE +.P +Changing the setting of +.IR LC_MESSAGES +has no effect on catalogs that have already been opened by calls to +\fIcatopen\fR(). +.P +In order to make use of different locale settings while multiple +threads are running, applications should use +\fIuselocale\fR() +in preference to +\fIsetlocale\fR(). +.SH RATIONALE +References to the international environment or locale in the following +text relate to the global locale for the process. This can be overridden +for individual threads using +\fIuselocale\fR(). +.P +The ISO\ C standard +defines a collection of functions to support internationalization. +One of the most significant aspects of these functions is a facility +to set and query the \fIinternational environment\fP. +The international environment is a repository of information that +affects the behavior of certain functionality, namely: +.IP " 1." 4 +Character handling +.IP " 2." 4 +Collating +.IP " 3." 4 +Date/time formatting +.IP " 4." 4 +Numeric editing +.IP " 5." 4 +Monetary formatting +.IP " 6." 4 +Messaging +.P +The +\fIsetlocale\fR() +function provides the application developer with the ability to set all +or portions, called \fIcategories\fP, of the international environment. +These categories correspond to the areas of functionality mentioned +above. The syntax for +\fIsetlocale\fR() +is as follows: +.sp +.RS 4 +.nf + +char *setlocale(int \fIcategory\fP, const char *\fIlocale\fP); +.fi +.P +.RE +.P +where +.IR category +is the name of one of following categories, namely: +.sp +.RS +LC_COLLATE +LC_CTYPE +LC_MESSAGES +LC_MONETARY +LC_NUMERIC +LC_TIME +.RE +.P +In addition, a special value called LC_ALL +directs +\fIsetlocale\fR() +to set all categories. +.P +There are two primary uses of +\fIsetlocale\fR(): +.IP " 1." 4 +Querying the international environment to find out what it is set to +.IP " 2." 4 +Setting the international environment, or +.IR locale , +to a specific value +.P +The behavior of +\fIsetlocale\fR() +in these two areas is described below. Since it is difficult to +describe the behavior in words, examples are used to illustrate the +behavior of specific uses. +.P +To query the international environment, +\fIsetlocale\fR() +is invoked with a specific category and the null pointer as the +locale. The null pointer is a special directive to +\fIsetlocale\fR() +that tells it to query rather than set the international environment. +The following syntax is used to query the name of the international +environment: +.sp +.RS 4 +.nf + +setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONETARY, \e + LC_NUMERIC, LC_TIME},(char *) NULL); +.fi +.P +.RE +.P +The +\fIsetlocale\fR() +function shall return the string corresponding to the current +international environment. This value may be used by a subsequent call to +\fIsetlocale\fR() +to reset the international environment to this value. However, it +should be noted that the return value from +\fIsetlocale\fR() +may be a pointer to a static area within the function and is not +guaranteed to remain unchanged (that is, it may be modified by a +subsequent call to +\fIsetlocale\fR()). +Therefore, if the purpose of calling +\fIsetlocale\fR() +is to save the value of the current international environment so it can +be changed and reset later, the return value should be copied to an +array of +.BR char +in the calling program. +.P +There are three ways to set the international environment with +\fIsetlocale\fR(): +.IP "\fIsetlocale\fP(\fIcategory\fP,\ \fIstring\fP)" 6 +.br +This usage sets a specific +.IR category +in the international environment to a specific value corresponding to +the value of the +.IR string . +A specific example is provided below: +.RS 6 +.sp +.RS 4 +.nf + +setlocale(LC_ALL, "fr_FR.ISO-8859-1"); +.fi +.P +.RE +.P +In this example, all categories of the international environment are +set to the locale corresponding to the string +.BR \(dqfr_FR.ISO-8859-1\(dq , +or to the French language as spoken in France using the ISO/IEC\ 8859\(hy1:\|1998 standard codeset. +.P +If the string does not correspond to a valid locale, +\fIsetlocale\fR() +shall return a null pointer and the international environment is not +changed. Otherwise, +\fIsetlocale\fR() +shall return the name of the locale just set. +.RE +.IP "\&\fIsetlocale\fP(\fIcategory\fP,\ \(dqC\(dq)" 6 +.br +The ISO\ C standard states that one locale must exist on all conforming +implementations. The name of the locale is C and corresponds to a +minimal international environment needed to support the C programming +language. +.IP "\&\fIsetlocale\fP(\fIcategory\fP,\ \(dq\^\(dq)" 6 +.br +This sets a specific category to an implementation-defined default. +This corresponds to the value of the environment variables. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "\fIcatopen\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalnum\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIisblank\fR\^(\|)", +.IR "\fIiscntrl\fR\^(\|)", +.IR "\fIisdigit\fR\^(\|)", +.IR "\fIisgraph\fR\^(\|)", +.IR "\fIislower\fR\^(\|)", +.IR "\fIisprint\fR\^(\|)", +.IR "\fIispunct\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIisupper\fR\^(\|)", +.IR "\fIiswalnum\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIiswblank\fR\^(\|)", +.IR "\fIiswcntrl\fR\^(\|)", +.IR "\fIiswctype\fR\^(\|)", +.IR "\fIiswdigit\fR\^(\|)", +.IR "\fIiswgraph\fR\^(\|)", +.IR "\fIiswlower\fR\^(\|)", +.IR "\fIiswprint\fR\^(\|)", +.IR "\fIiswpunct\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIiswupper\fR\^(\|)", +.IR "\fIiswxdigit\fR\^(\|)", +.IR "\fIisxdigit\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fImblen\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fInl_langinfo\fR\^(\|)", +.IR "\fIperror\fR\^(\|)", +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)", +.IR "\fIstrerror\fR\^(\|)", +.IR "\fIstrfmon\fR\^(\|)", +.IR "\fIstrsignal\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)", +.IR "\fItolower\fR\^(\|)", +.IR "\fItoupper\fR\^(\|)", +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)", +.IR "\fIwcscoll\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)", +.IR "\fIwcsxfrm\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setlogmask.3p b/upstream/archlinux/man3p/setlogmask.3p new file mode 100644 index 00000000..a6bb2909 --- /dev/null +++ b/upstream/archlinux/man3p/setlogmask.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETLOGMASK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setlogmask +\(em set the log priority mask +.SH SYNOPSIS +.LP +.nf +#include +.P +int setlogmask(int \fImaskpri\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcloselog\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setnetent.3p b/upstream/archlinux/man3p/setnetent.3p new file mode 100644 index 00000000..1957b010 --- /dev/null +++ b/upstream/archlinux/man3p/setnetent.3p @@ -0,0 +1,39 @@ +'\" et +.TH SETNETENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setnetent \(em network database function +.SH SYNOPSIS +.LP +.nf +#include +.P +void setnetent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendnetent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setpgid.3p b/upstream/archlinux/man3p/setpgid.3p new file mode 100644 index 00000000..24e7a178 --- /dev/null +++ b/upstream/archlinux/man3p/setpgid.3p @@ -0,0 +1,203 @@ +'\" et +.TH SETPGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setpgid +\(em set process group ID for job control +.SH SYNOPSIS +.LP +.nf +#include +.P +int setpgid(pid_t \fIpid\fP, pid_t \fIpgid\fP); +.fi +.SH DESCRIPTION +The +\fIsetpgid\fR() +function shall either join an existing process group or create a +new process group within the session of the calling process. +.P +The process group ID of a session leader shall not change. +.P +Upon successful completion, the process group ID of the process with +a process ID that matches +.IR pid +shall be set to +.IR pgid . +.P +As a special case, if +.IR pid +is 0, the process ID of the calling process shall be used. Also, if +.IR pgid +is 0, the process ID of the indicated process shall be used. +.SH "RETURN VALUE" +Upon successful completion, +\fIsetpgid\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIsetpgid\fR() +function shall fail if: +.TP +.BR EACCES +The value of the +.IR pid +argument matches the process ID of a child process of the calling +process and the child process has successfully executed one of the +.IR exec +functions. +.TP +.BR EINVAL +The value of the +.IR pgid +argument is less than 0, or is not a value supported by the +implementation. +.TP +.BR EPERM +The process indicated by the +.IR pid +argument is a session leader. +.TP +.BR EPERM +The value of the +.IR pid +argument matches the process ID of a child process of the calling +process and the child process is not in the same session as the calling +process. +.TP +.BR EPERM +The value of the +.IR pgid +argument is valid but does not match the process ID of the process +indicated by the +.IR pid +argument and there is no process with a process group ID that matches +the value of the +.IR pgid +argument in the same session as the calling process. +.TP +.BR ESRCH +The value of the +.IR pid +argument does not match the process ID of the calling process or of a +child process of the calling process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIsetpgid\fR() +function shall group processes together for the purpose of +signaling, placement in foreground or background, +and other job control actions. +.P +The +\fIsetpgid\fR() +function is similar to the +\fIsetpgrp\fR() +function of 4.2 BSD, except that 4.2 BSD allowed the specified new process +group to assume any value. This presents certain security problems and +is more +flexible than necessary to support job control. +.P +To provide tighter security, +\fIsetpgid\fR() +only allows the calling process to join a process group already in use +inside its session or create a new process group +whose process group ID was equal to its process ID. +.P +When a job control shell spawns a new job, the processes in the +job must be placed into a new process group via +\fIsetpgid\fR(). +There are two timing constraints involved in this action: +.IP " 1." 4 +The new process must be placed in the new process group before the +appropriate program is launched via one of the +.IR exec +functions. +.IP " 2." 4 +The new process must be placed in the new process group before the +shell can correctly send signals to the new process group. +.P +To address these constraints, the following actions are performed. The +new processes call +\fIsetpgid\fR() +to alter their own process groups after +\fIfork\fR() +but before +.IR exec . +This satisfies the first constraint. Under 4.3 BSD, the second +constraint is satisfied by the synchronization property of +.IR vfork (\|); +that is, the shell is suspended until the child has completed the +.IR exec , +thus ensuring that the child has completed the +\fIsetpgid\fR(). +A new version of +\fIfork\fR() +with this same synchronization property was considered, but it was +decided instead to merely allow the parent shell process to adjust the +process group of its child processes via +\fIsetpgid\fR(). +Both timing constraints are now satisfied by having both the parent +shell and the child attempt to adjust the process group of the child +process; it does not matter which succeeds first. +.P +Since it would be confusing to an application to have its process +group change after it began executing (that is, after +.IR exec ), +and because the child process would already have adjusted its process +group before this, the +.BR [EACCES] +error was added to disallow this. +.P +One non-obvious use of +\fIsetpgid\fR() +is to allow a job control shell to return itself to its original +process group (the one in effect when the job control shell was +executed). A job control shell does this before returning control back +to its parent when it is terminating or suspending itself as a way of +restoring its job control ``state'' back to what its parent would +expect. (Note that the original process group of the job control shell +typically matches the process group of its parent, but this is not +necessarily always the case.) +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetpgrp\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)", +.IR "\fItcsetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setpgrp.3p b/upstream/archlinux/man3p/setpgrp.3p new file mode 100644 index 00000000..fa27fcae --- /dev/null +++ b/upstream/archlinux/man3p/setpgrp.3p @@ -0,0 +1,87 @@ +'\" et +.TH SETPGRP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setpgrp +\(em set the process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t setpgrp(void); +.fi +.SH DESCRIPTION +If the calling process is not already a session leader, +\fIsetpgrp\fR() +sets the process group ID of the calling process to the process ID of +the calling process. If +\fIsetpgrp\fR() +creates a new session, then the new session has no controlling +terminal. +.P +The +\fIsetpgrp\fR() +function has no effect when the calling process is a session leader. +.SH "RETURN VALUE" +Upon completion, +\fIsetpgrp\fR() +shall return the process group ID. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +It is unspecified whether this function behaves as +.IR setpgid (0,0) +or +\fIsetsid\fR() +unless the process is already a session leader. Therefore, applications +are encouraged to use +\fIsetpgid\fR() +or +\fIsetsid\fR() +as appropriate. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIsetpgrp\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIgetpid\fR\^(\|)", +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetsid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setpriority.3p b/upstream/archlinux/man3p/setpriority.3p new file mode 100644 index 00000000..b30330ed --- /dev/null +++ b/upstream/archlinux/man3p/setpriority.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETPRIORITY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setpriority +\(em set the nice value +.SH SYNOPSIS +.LP +.nf +#include +.P +int setpriority(int \fIwhich\fP, id_t \fIwho\fP, int \fInice\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetpriority\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setprotoent.3p b/upstream/archlinux/man3p/setprotoent.3p new file mode 100644 index 00000000..e46f97af --- /dev/null +++ b/upstream/archlinux/man3p/setprotoent.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETPROTOENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setprotoent +\(em network protocol database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void setprotoent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendprotoent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setpwent.3p b/upstream/archlinux/man3p/setpwent.3p new file mode 100644 index 00000000..06bbf9e6 --- /dev/null +++ b/upstream/archlinux/man3p/setpwent.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETPWENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setpwent +\(em user database function +.SH SYNOPSIS +.LP +.nf +#include +.P +void setpwent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendpwent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setregid.3p b/upstream/archlinux/man3p/setregid.3p new file mode 100644 index 00000000..90f28444 --- /dev/null +++ b/upstream/archlinux/man3p/setregid.3p @@ -0,0 +1,137 @@ +'\" et +.TH SETREGID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setregid +\(em set real and effective group IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int setregid(gid_t \fIrgid\fP, gid_t \fIegid\fP); +.fi +.SH DESCRIPTION +The +\fIsetregid\fR() +function shall set the real and effective group IDs of the calling +process. +.P +If +.IR rgid +is \-1, the real group ID shall not be changed; if +.IR egid +is \-1, the effective group ID shall not be changed. +.P +The real and effective group IDs may be set to different values in the +same call. +.P +Only a process with appropriate privileges can set the real group ID +and the effective group ID to any valid value. +.P +A non-privileged process can set either the real group ID to the saved +set-group-ID from one of the +.IR exec +family of functions, or the effective group ID to the saved +set-group-ID or the real group ID. +.P +If the real group ID is being set (\c +.IR rgid +is not \-1), or the effective group ID is being set to a value not +equal to the real group ID, then the saved set-group-ID of the current +process shall be set equal to the new effective group ID. +.P +Any supplementary group IDs of the calling process remain unchanged. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error, and neither of the group IDs are changed. +.SH ERRORS +The +\fIsetregid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR rgid +or +.IR egid +argument is invalid or out-of-range. +.TP +.BR EPERM +The process does not have appropriate privileges and a change other +than changing the real group ID to the saved set-group-ID, or changing +the effective group ID to the real group ID or the saved set-group-ID, +was requested. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If a non-privileged set-group-ID process sets its effective group ID to +its real group ID, it can only set its effective group ID back to the +previous value if +.IR rgid +was \-1 in the +\fIsetregid\fR() +call, since the saved-group-ID is not changed in that case. If +.IR rgid +was equal to the real group ID in the +\fIsetregid\fR() +call, then the saved set-group-ID will also have been changed to the +real user ID. +.SH RATIONALE +Earlier versions of this standard did not specify whether the saved +set-group-ID was affected by +\fIsetregid\fR() +calls. This version specifies common existing practice that constitutes an +important security feature. The ability to set both the effective group +ID and saved set-group-ID to be the same as the real group ID means that +any security weakness in code that is executed after that point cannot +result in malicious code being executed with the previous effective +group ID. Privileged applications could already do this using just +\fIsetgid\fR(), +but for non-privileged applications the only standard method available +is to use this feature of +\fIsetregid\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setreuid.3p b/upstream/archlinux/man3p/setreuid.3p new file mode 100644 index 00000000..d770ca90 --- /dev/null +++ b/upstream/archlinux/man3p/setreuid.3p @@ -0,0 +1,143 @@ +'\" et +.TH SETREUID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setreuid +\(em set real and effective user IDs +.SH SYNOPSIS +.LP +.nf +#include +.P +int setreuid(uid_t \fIruid\fP, uid_t \fIeuid\fP); +.fi +.SH DESCRIPTION +The +\fIsetreuid\fR() +function shall set the real and effective user IDs of the current +process to the values specified by the +.IR ruid +and +.IR euid +arguments. If +.IR ruid +or +.IR euid +is \-1, the corresponding effective or real user ID of the current +process shall be left unchanged. +.P +A process with appropriate privileges can set either ID to any value. +An unprivileged process can only set the effective user ID if the +.IR euid +argument is equal to either the real, effective, or saved user ID of +the process. +.P +If the real user ID is being set (\c +.IR ruid +is not \-1), or the effective user ID is being set to a value not +equal to the real user ID, then the saved set-user-ID of the current +process shall be set equal to the new effective user ID. +.P +It is unspecified whether a process without appropriate privileges is +permitted to change the real user ID to match the current effective user +ID or saved set-user-ID of the process. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetreuid\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR ruid +or +.IR euid +argument is invalid or out-of-range. +.TP +.BR EPERM +The current process does not have appropriate privileges, and either an +attempt was made to change the effective user ID to a value other than +the real user ID or the saved set-user-ID or an attempt was made to +change the real user ID to a value not permitted by the +implementation. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Setting the Effective User ID to the Real User ID" +.P +The following example sets the effective user ID of the calling process +to the real user ID, so that files created later will be owned by the +current user. It also sets the saved set-user-ID to the real user ID, +so any future attempt to set the effective user ID back to its previous +value will fail. +.sp +.RS 4 +.nf + +#include +#include +\&... +setreuid(getuid(), getuid()); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Earlier versions of this standard did not specify whether the saved +set-user-ID was affected by +\fIsetreuid\fR() +calls. This version specifies common existing practice that constitutes +an important security feature. The ability to set both the effective user +ID and saved set-user-ID to be the same as the real user ID means that +any security weakness in code that is executed after that point cannot +result in malicious code being executed with the previous effective user +ID. Privileged applications could already do this using just +\fIsetuid\fR(), +but for non-privileged applications the only standard method available +is to use this feature of +\fIsetreuid\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setrlimit.3p b/upstream/archlinux/man3p/setrlimit.3p new file mode 100644 index 00000000..782b0cd6 --- /dev/null +++ b/upstream/archlinux/man3p/setrlimit.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETRLIMIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setrlimit +\(em control maximum resource consumption +.SH SYNOPSIS +.LP +.nf +#include +.P +int setrlimit(int \fIresource\fP, const struct rlimit *\fIrlp\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIgetrlimit\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setservent.3p b/upstream/archlinux/man3p/setservent.3p new file mode 100644 index 00000000..c0b1021d --- /dev/null +++ b/upstream/archlinux/man3p/setservent.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETSERVENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setservent +\(em network services database functions +.SH SYNOPSIS +.LP +.nf +#include +.P +void setservent(int \fIstayopen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendservent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setsid.3p b/upstream/archlinux/man3p/setsid.3p new file mode 100644 index 00000000..b9537f1b --- /dev/null +++ b/upstream/archlinux/man3p/setsid.3p @@ -0,0 +1,113 @@ +'\" et +.TH SETSID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setsid +\(em create session and set process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t setsid(void); +.fi +.SH DESCRIPTION +The +\fIsetsid\fR() +function shall create a new session, if the calling process is not a +process group leader. Upon return the calling process shall be the +session leader of this new session, shall be the process group leader +of a new process group, and shall have no controlling terminal. The +process group ID of the calling process shall be set equal to the +process ID of the calling process. The calling process shall be the +only process in the new process group and the only process in the new +session. +.SH "RETURN VALUE" +Upon successful completion, +\fIsetsid\fR() +shall return the value of the new process group ID of the calling +process. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsetsid\fR() +function shall fail if: +.TP +.BR 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. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIsetsid\fR() +function is similar to the +\fIsetpgrp\fR() +function of System V. +System V, without job control, groups processes into +process groups and creates new process groups via +\fIsetpgrp\fR(); +only one process group may be part of a login session. +.P +Job control allows multiple process groups within a login session. In +order to limit job control actions so that they can only affect +processes in the same login session, this volume of POSIX.1\(hy2017 adds the concept of a +session that is created via +\fIsetsid\fR(). +The +\fIsetsid\fR() +function also creates the initial process group contained in the +session. Additional process groups can be created via the +\fIsetpgid\fR() +function. A System V process group would correspond to a POSIX System +Interfaces session containing a single POSIX process group. Note that +this function requires that the calling process not be a process group +leader. The usual way to ensure this is true is to create a new process +with +\fIfork\fR() +and have it call +\fIsetsid\fR(). +The +\fIfork\fR() +function guarantees that the process ID of the new process does not +match any existing process group ID. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fIsetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setsockopt.3p b/upstream/archlinux/man3p/setsockopt.3p new file mode 100644 index 00000000..49e71c8f --- /dev/null +++ b/upstream/archlinux/man3p/setsockopt.3p @@ -0,0 +1,167 @@ +'\" et +.TH SETSOCKOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setsockopt +\(em set the socket options +.SH SYNOPSIS +.LP +.nf +#include +.P +int setsockopt(int \fIsocket\fP, int \fIlevel\fP, int \fIoption_name\fP, + const void *\fIoption_value\fP, socklen_t \fIoption_len\fP); +.fi +.SH DESCRIPTION +The +\fIsetsockopt\fR() +function shall set the option specified by the +.IR option_name +argument, at the protocol level specified by the +.IR level +argument, to the value pointed to by the +.IR option_value +argument for the socket associated with the file descriptor specified +by the +.IR socket +argument. +.P +The +.IR level +argument specifies the protocol level at which the option resides. To +set options at the socket level, specify the +.IR level +argument as SOL_SOCKET. To set options at other levels, supply the +appropriate +.IR level +identifier for the protocol controlling the option. For example, to +indicate that an option is interpreted by the TCP (Transport Control +Protocol), set +.IR level +to IPPROTO_TCP as defined in the +.IR +header. +.P +The +.IR option_name +argument specifies a single option to set. It can be one of the +socket-level options defined in +.IR "\fB\fP" +and described in +.IR "Section 2.10.16" ", " "Use of Options". +If +.IR option_name +is equal to SO_RCVTIMEO or SO_SNDTIMEO and the implementation supports +setting the option, it is unspecified whether the +.BR "struct timeval" +pointed to by +.IR option_value +is stored as provided by this function or is rounded up to align with +the resolution of the clock being used. If +\fIsetsockopt\fR() +is called with +.IR option_name +equal to SO_ACCEPTCONN, SO_ERROR, or SO_TYPE, the behavior is unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIsetsockopt\fR() +shall return 0. Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetsockopt\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EDOM +The send and receive timeout values are too big to fit into the timeout +fields in the socket structure. +.TP +.BR EINVAL +The specified option is invalid at the specified socket level or the +socket has been shut down. +.TP +.BR EISCONN +The socket is already connected, and a specified option cannot be set +while the socket is connected. +.TP +.BR ENOPROTOOPT +.br +The option is not supported by the protocol. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.P +The +\fIsetsockopt\fR() +function may fail if: +.TP +.BR ENOMEM +There was insufficient memory available for the operation to complete. +.TP +.BR ENOBUFS +Insufficient resources are available in the system to complete the +call. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The +\fIsetsockopt\fR() +function provides an application program with the means to control +socket behavior. An application program can use +\fIsetsockopt\fR() +to allocate buffer space, control timeouts, or permit socket data +broadcasts. The +.IR +header defines the socket-level options available to +\fIsetsockopt\fR(). +.P +Options may exist at multiple protocol levels. The SO_ options are +always present at the uppermost socket level. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.10" ", " "Sockets", +.IR "\fIbind\fR\^(\|)", +.IR "\fIendprotoent\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setstate.3p b/upstream/archlinux/man3p/setstate.3p new file mode 100644 index 00000000..fecd65ae --- /dev/null +++ b/upstream/archlinux/man3p/setstate.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETSTATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setstate +\(em switch pseudo-random number generator state arrays +.SH SYNOPSIS +.LP +.nf +#include +.P +char *setstate(char *\fIstate\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinitstate\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setuid.3p b/upstream/archlinux/man3p/setuid.3p new file mode 100644 index 00000000..610582f0 --- /dev/null +++ b/upstream/archlinux/man3p/setuid.3p @@ -0,0 +1,257 @@ +'\" et +.TH SETUID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setuid +\(em set user ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int setuid(uid_t \fIuid\fP); +.fi +.SH DESCRIPTION +If the process has appropriate privileges, +\fIsetuid\fR() +shall set the real user ID, effective user ID, and the saved +set-user-ID of the calling process to +.IR uid . +.P +If the process does not have appropriate privileges, but +.IR uid +is equal to the real user ID or the saved set-user-ID, +\fIsetuid\fR() +shall set the effective user ID to +.IR uid ; +the real user ID and saved set-user-ID shall remain unchanged. +.P +The +\fIsetuid\fR() +function shall not affect the supplementary group list in any way. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsetuid\fR() +function shall fail, return \-1, and set +.IR errno +to the corresponding value if one or more of the following are true: +.TP +.BR EINVAL +The value of the +.IR uid +argument is invalid and not supported by the implementation. +.TP +.BR EPERM +The process does not have appropriate privileges and +.IR uid +does not match the real user ID or the saved set-user-ID. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The various behaviors of the +\fIsetuid\fR() +and +\fIsetgid\fR() +functions when called by non-privileged processes reflect the behavior +of different historical implementations. For portability, it is +recommended that new non-privileged applications use the +\fIseteuid\fR() +and +\fIsetegid\fR() +functions instead. +.P +The saved set-user-ID capability allows a program to regain the +effective user ID established at the last +.IR exec +call. Similarly, the saved set-group-ID capability allows a program to +regain the effective group ID established at the last +.IR exec +call. These capabilities are derived from System V. Without them, a +program might have to run as superuser in order to perform the same +functions, because superuser can write on the user's files. This is a +problem because such a program can write on any user's files, and so +must be carefully written to emulate the permissions of the calling +process properly. In System V, these capabilities have traditionally +been implemented only via the +\fIsetuid\fR() +and +\fIsetgid\fR() +functions for non-privileged processes. The fact that the behavior of +those functions was different for privileged processes made them +difficult to use. The POSIX.1\(hy1990 standard defined the +\fIsetuid\fR() +function to behave differently for privileged and unprivileged users. +When the caller had appropriate privileges, the function set the real +user ID, effective user ID, and saved set-user ID of the calling process +on implementations that supported it. When the caller did not have +appropriate privileges, the function set only the effective user ID, +subject to permission checks. The former use is generally needed for +utilities like +.IR login +and +.IR su , +which are not conforming applications and thus outside the scope of +POSIX.1\(hy2008. These utilities wish to change the user ID irrevocably to a new +value, generally that of an unprivileged user. The latter use is needed +for conforming applications that are installed with the set-user-ID bit +and need to perform operations using the real user ID. +.P +POSIX.1\(hy2008 augments the latter functionality with a mandatory feature named +_POSIX_SAVED_IDS. This feature permits a set-user-ID application to +switch its effective user ID back and forth between the values of its +.IR exec -time +real user ID and effective user ID. Unfortunately, the POSIX.1\(hy1990 standard did not +permit a conforming application using this feature to work properly when +it happened to be executed with (implementation-defined) +appropriate privileges. Furthermore, the application did not even have a +means to tell whether it had this privilege. Since the saved +set-user-ID feature is quite desirable for applications, as evidenced +by the fact that NIST required it in FIPS 151\(hy2, it has been mandated by +POSIX.1\(hy2008. However, there are implementors who have been reluctant to +support it given the limitation described above. +.P +The 4.3BSD system handles the problem by supporting separate +functions: +\fIsetuid\fR() +(which always sets both the real and effective user IDs, like +\fIsetuid\fR() +in POSIX.1\(hy2008 for privileged users), and +\fIseteuid\fR() +(which always sets just the effective user ID, like +\fIsetuid\fR() +in POSIX.1\(hy2008 for non-privileged users). This separation of functionality +into distinct functions seems desirable. 4.3BSD does not support the +saved set-user-ID feature. It supports similar functionality of +switching the effective user ID back and forth via +\fIsetreuid\fR(), +which permits reversing the real and effective user IDs. This model +seems less desirable than the saved set-user-ID because the real user +ID changes as a side-effect. The current 4.4BSD includes saved +effective IDs and uses them for +\fIseteuid\fR() +and +\fIsetegid\fR() +as described above. The +\fIsetreuid\fR() +and +\fIsetregid\fR() +functions will be deprecated or removed. +.P +The solution here is: +.IP " *" 4 +Require that all implementations support the functionality of the saved +set-user-ID, which is set by the +.IR exec +functions and by privileged calls to +\fIsetuid\fR(). +.IP " *" 4 +Add the +\fIseteuid\fR() +and +\fIsetegid\fR() +functions as portable alternatives to +\fIsetuid\fR() +and +\fIsetgid\fR() +for non-privileged and privileged processes. +.P +Historical systems have provided two mechanisms for a set-user-ID +process to change its effective user ID to be the same as its real user +ID in such a way that it could return to the original effective user +ID: the use of the +\fIsetuid\fR() +function in the presence of a saved set-user-ID, or the use of the BSD +\fIsetreuid\fR() +function, which was able to swap the real and effective user IDs. The +changes included in POSIX.1\(hy2008 provide a new mechanism using +\fIseteuid\fR() +in conjunction with a saved set-user-ID. Thus, all implementations with +the new +\fIseteuid\fR() +mechanism will have a saved set-user-ID for each process, and most of +the behavior controlled by _POSIX_SAVED_IDS has been changed +to agree with the case where the option was defined. The +\fIkill\fR() +function is an exception. Implementors of the new +\fIseteuid\fR() +mechanism will generally be required to maintain compatibility with the +older mechanisms previously supported by their systems. However, +compatibility with this use of +\fIsetreuid\fR() +and with the _POSIX_SAVED_IDS behavior of +\fIkill\fR() +is unfortunately complicated. If an implementation with a saved +set-user-ID allows a process to use +\fIsetreuid\fR() +to swap its real and effective user IDs, but were to leave the saved +set-user-ID unmodified, the process would then have an effective user +ID equal to the original real user ID, and both real and saved +set-user-ID would be equal to the original effective user ID. In that +state, the real user would be unable to kill the process, even though +the effective user ID of the process matches that of the real user, if +the +\fIkill\fR() +behavior of _POSIX_SAVED_IDS was used. This is obviously not +acceptable. The alternative choice, which is used in at least one +implementation, is to change the saved set-user-ID to the effective +user ID during most calls to +\fIsetreuid\fR(). +The standard developers considered that alternative to be less correct +than the retention of the old behavior of +\fIkill\fR() +in such systems. Current conforming applications shall accommodate +either behavior from +\fIkill\fR(), +and there appears to be no strong reason for +\fIkill\fR() +to check the saved set-user-ID rather than the effective user ID. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetegid\fR\^(\|)", +.IR "\fIgeteuid\fR\^(\|)", +.IR "\fIgetgid\fR\^(\|)", +.IR "\fIgetuid\fR\^(\|)", +.IR "\fIsetegid\fR\^(\|)", +.IR "\fIseteuid\fR\^(\|)", +.IR "\fIsetgid\fR\^(\|)", +.IR "\fIsetregid\fR\^(\|)", +.IR "\fIsetreuid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setutxent.3p b/upstream/archlinux/man3p/setutxent.3p new file mode 100644 index 00000000..e22fda08 --- /dev/null +++ b/upstream/archlinux/man3p/setutxent.3p @@ -0,0 +1,40 @@ +'\" et +.TH SETUTXENT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setutxent +\(em reset the user accounting database to the first entry +.SH SYNOPSIS +.LP +.nf +#include +.P +void setutxent(void); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIendutxent\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/setvbuf.3p b/upstream/archlinux/man3p/setvbuf.3p new file mode 100644 index 00000000..35a5b330 --- /dev/null +++ b/upstream/archlinux/man3p/setvbuf.3p @@ -0,0 +1,126 @@ +'\" et +.TH SETVBUF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +setvbuf +\(em assign buffering to a stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int setvbuf(FILE *restrict \fIstream\fP, char *restrict \fIbuf\fP, int \fItype\fP, + size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIsetvbuf\fR() +function may be used after the stream pointed to by +.IR stream +is associated with an open file but before any other operation +(other than an unsuccessful call to +\fIsetvbuf\fR()) +is performed on the stream. The argument +.IR type +determines how +.IR stream +shall be buffered, as follows: +.IP " *" 4 +{_IOFBF} shall cause input/output to be fully buffered. +.IP " *" 4 +{_IOLBF} shall cause input/output to be line buffered. +.IP " *" 4 +{_IONBF} shall cause input/output to be unbuffered. +.P +If +.IR buf +is not a null pointer, the array it points to may be used instead of a +buffer allocated by +\fIsetvbuf\fR() +and the argument +.IR size +specifies the size of the array; otherwise, +.IR size +may determine the size of a buffer allocated by the +\fIsetvbuf\fR() +function. The contents of the array at any time are unspecified. +.P +For information about streams, see +.IR "Section 2.5" ", " "Standard I/O Streams". +.SH "RETURN VALUE" +Upon successful completion, +\fIsetvbuf\fR() +shall return 0. Otherwise, it shall return a non-zero value if an +invalid value is given for +.IR type +or if the request cannot be honored, +and may set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsetvbuf\fR() +function may fail if: +.TP +.BR EBADF +The file descriptor underlying +.IR stream +is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +A common source of error is allocating buffer space as an ``automatic'' +variable in a code block, and then failing to close the stream in the +same block. +.P +With +\fIsetvbuf\fR(), +allocating a buffer of +.IR size +bytes does not necessarily imply that all of +.IR size +bytes are used for the buffer area. +.P +Applications should note that many implementations only provide line +buffering on input from terminal devices. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/shm_open.3p b/upstream/archlinux/man3p/shm_open.3p new file mode 100644 index 00000000..04120b0a --- /dev/null +++ b/upstream/archlinux/man3p/shm_open.3p @@ -0,0 +1,405 @@ +'\" et +.TH SHM_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +shm_open +\(em open a shared memory object +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int shm_open(const char *\fIname\fP, int \fIoflag\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +The +\fIshm_open\fR() +function shall establish a connection between a shared memory object +and a file descriptor. It shall create an open file description that +refers to the shared memory object and a file descriptor that refers to +that open file description. The file descriptor shall be allocated as +described in +.IR "Section 2.14" ", " "File Descriptor Allocation", +and can be used by other functions to refer to that shared memory object. +The +.IR name +argument points to a string naming a shared memory object. It is +unspecified whether the name appears in the file system and is visible +to other functions that take pathnames as arguments. The +.IR name +argument conforms to the construction rules for a pathname, except that +the interpretation of + +characters other than the leading + +character in +.IR name +is implementation-defined, and that the length limits for the +.IR name +argument are implementation-defined and need not be the same as the +pathname limits +{PATH_MAX} +and +{NAME_MAX}. +If +.IR name +begins with the + +character, then processes calling +\fIshm_open\fR() +with the same value of +.IR name +refer to the same shared memory object, as long as that name has not +been removed. If +.IR name +does not begin with the + +character, the effect is implementation-defined. +.P +If successful, +\fIshm_open\fR() +shall return a file descriptor for the shared memory object. +The open file description is new, and therefore the file descriptor +does not share it with any other processes. It is unspecified whether +the file offset is set. The FD_CLOEXEC +file descriptor flag associated with the new file descriptor is set. +.P +The file status flags and file access modes of the open file +description are according to the value of +.IR oflag . +The +.IR oflag +argument is the bitwise-inclusive OR of the following flags defined in +the +.IR +header. Applications specify exactly one of the first two values +(access modes) below in the value of +.IR oflag : +.IP O_RDONLY 12 +Open for read access only. +.IP O_RDWR 12 +Open for read or write access. +.P +Any combination of the remaining flags may be specified in the value of +.IR oflag : +.IP O_CREAT 12 +If the shared memory object exists, this flag has no effect, except +as noted under O_EXCL below. Otherwise, the shared memory object is +created. The user ID of the shared memory object shall be set to the +effective user ID of the process. The group ID of the shared memory object +shall be set to the effective group ID of the process; however, if the +.IR name +argument is visible in the file system, the group ID may be set to the +group ID of the containing directory. The permission bits of the shared +memory object shall be set to the value of the +.IR mode +argument except those set in the file mode creation mask of the +process. When bits in +.IR mode +other than the file permission bits are set, the effect is +unspecified. The +.IR mode +argument does not affect whether the shared memory object is opened for +reading, for writing, or for both. The shared memory object has a size +of zero. +.IP O_EXCL 12 +If O_EXCL and O_CREAT are set, +\fIshm_open\fR() +fails if the shared memory object exists. The check for the existence +of the shared memory object and the creation of the object if it does +not exist is atomic with respect to other processes executing +\fIshm_open\fR() +naming the same shared memory object with O_EXCL and O_CREAT set. If +O_EXCL is set and O_CREAT is not set, the result is undefined. +.IP O_TRUNC 12 +If the shared memory object exists, and it is successfully opened +O_RDWR, the object shall be truncated to zero length and the mode and +owner shall be unchanged by this function call. The result of using +O_TRUNC with O_RDONLY is undefined. +.P +When a shared memory object is created, the state of the shared memory +object, including all data associated with the shared memory object, +persists until the shared memory object is unlinked and all other +references are gone. It is unspecified whether the name and shared +memory object state remain valid after a system reboot. +.SH "RETURN VALUE" +Upon successful completion, the +\fIshm_open\fR() +function shall return a non-negative integer representing the +file descriptor. Otherwise, it shall return \-1 and +set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIshm_open\fR() +function shall fail if: +.TP +.BR EACCES +The shared memory object exists and the permissions specified by +.IR oflag +are denied, or the shared memory object does not exist and permission +to create the shared memory object is denied, or O_TRUNC is specified +and write permission is denied. +.TP +.BR EEXIST +O_CREAT and O_EXCL are set and +the named shared memory object already exists. +.TP +.BR EINTR +The +\fIshm_open\fR() +operation was interrupted by a signal. +.TP +.BR EINVAL +The +\fIshm_open\fR() +operation is not supported for the given name. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +Too many shared memory objects are currently open in the system. +.TP +.BR ENOENT +O_CREAT is not set and the named shared memory object does not exist. +.TP +.BR ENOSPC +There is insufficient space for the creation of the new shared memory +object. +.P +The +\fIshm_open\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating and Mapping a Shared Memory Object" +.P +The following code segment demonstrates the use of +\fIshm_open\fR() +to create a shared memory object which is then sized using +\fIftruncate\fR() +before being mapped into the process address space using +\fImmap\fR(): +.sp +.RS 4 +.nf + +#include +#include +\&... +.P +#define MAX_LEN 10000 +struct region { /* Defines "structure" of shared memory */ + int len; + char buf[MAX_LEN]; +}; +struct region *rptr; +int fd; +.P +/* Create shared memory object and set its size */ +.P +fd = shm_open("/myregion", O_CREAT | O_RDWR, S_IRUSR | S_IWUSR); +if (fd == -1) + /* Handle error */; +.P +if (ftruncate(fd, sizeof(struct region)) == -1) + /* Handle error */; +.P +/* Map shared memory object */ +.P +rptr = mmap(NULL, sizeof(struct region), + PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0); +if (rptr == MAP_FAILED) + /* Handle error */; +.P +/* Now we can refer to mapped region using fields of rptr; + for example, rptr->len */ +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +When the Memory Mapped Files option is supported, the normal +\fIopen\fR() +call is used to obtain a descriptor to a file to be mapped according to +existing practice with +\fImmap\fR(). +When the Shared Memory Objects option is supported, the +\fIshm_open\fR() +function shall obtain a descriptor to the shared memory object +to be mapped. +.P +There is ample precedent for having a file descriptor represent several +types of objects. In the POSIX.1\(hy1990 standard, a file descriptor can represent a +file, a pipe, a FIFO, a tty, or a directory. Many implementations +simply have an operations vector, which is indexed by the file +descriptor type and does very different operations. Note that in some +cases the file descriptor passed to generic operations on file +descriptors is returned by +\fIopen\fR() +or +\fIcreat\fR() +and in some cases returned by alternate functions, such as +\fIpipe\fR(). +The latter technique is used by +\fIshm_open\fR(). +.P +Note that such shared memory objects can actually be implemented as +mapped files. In both cases, the size can be set after the open using +\fIftruncate\fR(). +The +\fIshm_open\fR() +function itself does not create a shared object of a specified size +because this would duplicate an extant function that set the size of +an object referenced by a file descriptor. +.P +On implementations where memory objects are implemented using the +existing file system, the +\fIshm_open\fR() +function may be implemented using a macro that invokes +\fIopen\fR(), +and the +\fIshm_unlink\fR() +function may be implemented using a macro that invokes +\fIunlink\fR(). +.P +For implementations without a permanent file system, the definition of +the name of the memory objects is allowed not to survive a system +reboot. Note that this allows systems with a permanent file system to +implement memory objects as data structures internal to the +implementation as well. +.P +On implementations that choose to implement memory objects using memory +directly, a +\fIshm_open\fR() +followed by an +\fIftruncate\fR() +and +\fIclose\fR() +can be used to preallocate a shared memory area and to set the size of +that preallocation. This may be necessary for systems without virtual +memory hardware support in order to ensure that the memory is +contiguous. +.P +The set of valid open flags to +\fIshm_open\fR() +was restricted to O_RDONLY, O_RDWR, O_CREAT, and O_TRUNC +because these could be easily implemented on most memory mapping +systems. This volume of POSIX.1\(hy2017 is silent on the results if the implementation +cannot supply the requested file access because of +implementation-defined reasons, including hardware ones. +.P +The error conditions +.BR [EACCES] +and +.BR [ENOTSUP] +are provided to inform the application that the implementation cannot +complete a request. +.P +.BR [EACCES] +indicates for implementation-defined reasons, probably +hardware-related, that the implementation cannot comply with a +requested mode because it conflicts with another requested mode. An +example might be that an application desires to open a memory object +two times, mapping different areas with different access modes. If the +implementation cannot map a single area into a process space in two +places, which would be required if different access modes were required +for the two areas, then the implementation may inform the application +at the time of the second open. +.P +.BR [ENOTSUP] +indicates for implementation-defined reasons, probably +hardware-related, that the implementation cannot comply with a +requested mode at all. An example would be that the hardware of the +implementation cannot support write-only shared memory areas. +.P +On all implementations, it may be desirable to restrict the location of +the memory objects to specific file systems for performance (such as a +RAM disk) or implementation-defined reasons (shared memory supported +directly only on certain file systems). The +\fIshm_open\fR() +function may be used to enforce these restrictions. There are a number +of methods available to the application to determine an appropriate +name of the file or the location of an appropriate directory. One way +is from the environment via +\fIgetenv\fR(). +Another would be from a configuration file. +.P +This volume of POSIX.1\(hy2017 specifies that memory objects have initial contents of +zero when created. This is consistent with current behavior for both +files and newly allocated memory. For those implementations that use +physical memory, it would be possible that such implementations could +simply use available memory and give it to the process uninitialized. +This, however, is not consistent with standard behavior for the +uninitialized data area, the stack, and of course, files. Finally, it +is highly desirable to set the allocated memory to zero for security +reasons. Thus, initializing memory objects to zero is required. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIshm_open\fR() +and +\fIshm_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "File Descriptor Allocation", +.IR "\fIclose\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)", +.IR "\fIumask\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/shm_unlink.3p b/upstream/archlinux/man3p/shm_unlink.3p new file mode 100644 index 00000000..18aa118f --- /dev/null +++ b/upstream/archlinux/man3p/shm_unlink.3p @@ -0,0 +1,141 @@ +'\" et +.TH SHM_UNLINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +shm_unlink +\(em remove a shared memory object +(\fBREALTIME\fP) +.SH SYNOPSIS +.LP +.nf +#include +.P +int shm_unlink(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIshm_unlink\fR() +function shall remove the name of the shared memory object named +by the string pointed to by +.IR name . +.P +If one or more references to the shared memory object exist when the +object is unlinked, the name shall be removed before +\fIshm_unlink\fR() +returns, but the removal of the memory object contents shall be postponed +until all open and map references to the shared memory object have been +removed. +.P +Even if the object continues to exist after the last +\fIshm_unlink\fR(), +reuse of the name shall subsequently cause +\fIshm_open\fR() +to behave as if no shared memory object of this name exists (that is, +\fIshm_open\fR() +will fail if O_CREAT is not set, or will create a new shared memory +object if O_CREAT is set). +.SH "RETURN VALUE" +Upon successful completion, a value of zero shall be returned. +Otherwise, a value of \-1 shall be returned and +.IR errno +set to indicate the error. If \-1 is returned, the named shared +memory object shall not be changed by this function call. +.SH ERRORS +The +\fIshm_unlink\fR() +function shall fail if: +.TP +.BR EACCES +Permission is denied to unlink the named shared memory object. +.TP +.BR ENOENT +The named shared memory object does not exist. +.P +The +\fIshm_unlink\fR() +function may fail if: +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR name +argument exceeds +{_POSIX_PATH_MAX} +on systems that do not support the XSI option +or exceeds +{_XOPEN_PATH_MAX} +on XSI systems, +or has a pathname component that is longer than +{_POSIX_NAME_MAX} +on systems that do not support the XSI option +or longer than +{_XOPEN_NAME_MAX} +on XSI systems. +A call to +\fIshm_unlink\fR() +with a +.IR name +argument that contains the same shared memory object name as was +previously used in a successful +\fIshm_open\fR() +call shall not give an +.BR [ENAMETOOLONG] +error. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Names of memory objects that were allocated with +\fIopen\fR() +are deleted with +\fIunlink\fR() +in the usual fashion. Names of memory objects that were allocated with +\fIshm_open\fR() +are deleted with +\fIshm_unlink\fR(). +Note that the actual memory object is not destroyed until the +last close and unmap on it have occurred if it was already in use. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +A future version might require the +\fIshm_open\fR() +and +\fIshm_unlink\fR() +functions to have semantics similar to normal file system operations. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fImmap\fR\^(\|)", +.IR "\fImunmap\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/shmat.3p b/upstream/archlinux/man3p/shmat.3p new file mode 100644 index 00000000..b588cb59 --- /dev/null +++ b/upstream/archlinux/man3p/shmat.3p @@ -0,0 +1,154 @@ +'\" et +.TH SHMAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +shmat +\(em XSI shared memory attach operation +.SH SYNOPSIS +.LP +.nf +#include +.P +void *shmat(int \fIshmid\fP, const void *\fIshmaddr\fP, int \fIshmflg\fP); +.fi +.SH DESCRIPTION +The +\fIshmat\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmat\fR() +function attaches the shared memory segment associated with the shared +memory identifier specified by +.IR shmid +to the address space of the calling process. The segment is attached +at the address specified by one of the following criteria: +.IP " *" 4 +If +.IR shmaddr +is a null pointer, the segment is attached at the first available +address as selected by the system. +.IP " *" 4 +If +.IR shmaddr +is not a null pointer and (\fIshmflg\fP &SHM_RND) +is non-zero, the segment is attached at the address given by +(\fIshmaddr\fP \-((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)). The +character +.BR '%' +is the C-language remainder operator. +.IP " *" 4 +If +.IR shmaddr +is not a null pointer and (\fIshmflg\fP &SHM_RND) is 0, the segment is +attached at the address given by +.IR shmaddr . +.IP " *" 4 +The segment is attached for reading if (\fIshmflg\fP &SHM_RDONLY) +is non-zero and the calling process has read permission; otherwise, if +it is 0 and the calling process has read and write permission, the +segment is attached for reading and writing. +.SH "RETURN VALUE" +Upon successful completion, +\fIshmat\fR() +shall increment the value of +.IR shm_nattch +in the data structure associated with the shared memory ID of the +attached shared memory segment and return the segment's start address. +Also, the +.IR shm_atime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +Otherwise, the shared memory segment shall not be attached, +\fIshmat\fR() +shall return (\fBvoid *\fP)\-1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIshmat\fR() +function shall fail if: +.TP +.BR EACCES +Operation permission is denied to the calling process; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR shmid +is not a valid shared memory identifier, the +.IR shmaddr +is not a null pointer, and the value of +(\fIshmaddr\fP \-((\fIuintptr_t\fP)\fIshmaddr\fP %SHMLBA)) +is an illegal address for attaching shared memory; or the +.IR shmaddr +is not a null pointer, (\fIshmflg\fP &SHM_RND) is 0, and the value of +.IR shmaddr +is an illegal address for attaching shared memory. +.TP +.BR EMFILE +The number of shared memory segments attached to the calling process +would exceed the system-imposed limit. +.TP +.BR ENOMEM +The available data space is not large enough to accommodate the shared +memory segment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/shmctl.3p b/upstream/archlinux/man3p/shmctl.3p new file mode 100644 index 00000000..7fa1af5b --- /dev/null +++ b/upstream/archlinux/man3p/shmctl.3p @@ -0,0 +1,192 @@ +'\" et +.TH SHMCTL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +shmctl +\(em XSI shared memory control operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int shmctl(int \fIshmid\fP, int \fIcmd\fP, struct shmid_ds *\fIbuf\fP); +.fi +.SH DESCRIPTION +The +\fIshmctl\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmctl\fR() +function provides a variety of shared memory control operations as +specified by +.IR cmd . +The following values for +.IR cmd +are available: +.IP IPC_STAT 12 +Place the current value of each member of the +.BR shmid_ds +data structure associated with +.IR shmid +into the structure pointed to by +.IR buf . +The contents of the structure are defined in +.IR . +.IP IPC_SET 12 +Set the value of the following members of the +.BR shmid_ds +data structure associated with +.IR shmid +to the corresponding value found in the structure pointed to by +.IR buf : +.RS 12 +.sp +.RS 4 +.nf + +shm_perm.uid +shm_perm.gid +shm_perm.mode \fRLow-order nine bits.\fP +.fi +.P +.RE +.P +Also, the +.IR shm_ctime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +IPC_SET can only be executed by a process that has an effective user ID +equal to either that of a process with appropriate privileges or to the +value of +.IR shm_perm.cuid +or +.IR shm_perm.uid +in the +.BR shmid_ds +data structure associated with +.IR shmid . +.RE +.IP IPC_RMID 12 +Remove the shared memory identifier specified by +.IR shmid +from the system and destroy the shared memory segment and +.BR shmid_ds +data structure associated with it. IPC_RMID can only be executed by a +process that has an effective user ID equal to either that of a process +with appropriate privileges or to the value of +.IR shm_perm.cuid +or +.IR shm_perm.uid +in the +.BR shmid_ds +data structure associated with +.IR shmid . +.SH "RETURN VALUE" +Upon successful completion, +\fIshmctl\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIshmctl\fR() +function shall fail if: +.TP +.BR EACCES +The argument +.IR cmd +is equal to IPC_STAT and the calling process does not have read +permission; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EINVAL +The value of +.IR shmid +is not a valid shared memory identifier, or the value of +.IR cmd +is not a valid command. +.TP +.BR EPERM +The argument +.IR cmd +is equal to IPC_RMID or IPC_SET and the effective user ID of the +calling process is not equal to that of a process with appropriate +privileges and it is not equal to the value of +.IR shm_perm.cuid +or +.IR shm_perm.uid +in the data structure associated with +.IR shmid . +.br +.P +The +\fIshmctl\fR() +function may fail if: +.TP +.BR EOVERFLOW +The +.IR cmd +argument is IPC_STAT and the +.IR gid +or +.IR uid +value is too large to be stored in the structure pointed to by the +.IR buf +argument. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/shmdt.3p b/upstream/archlinux/man3p/shmdt.3p new file mode 100644 index 00000000..01e95167 --- /dev/null +++ b/upstream/archlinux/man3p/shmdt.3p @@ -0,0 +1,107 @@ +'\" et +.TH SHMDT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +shmdt +\(em XSI shared memory detach operation +.SH SYNOPSIS +.LP +.nf +#include +.P +int shmdt(const void *\fIshmaddr\fP); +.fi +.SH DESCRIPTION +The +\fIshmdt\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmdt\fR() +function detaches the shared memory segment located at the address +specified by +.IR shmaddr +from the address space of the calling process. +.SH "RETURN VALUE" +Upon successful completion, +\fIshmdt\fR() +shall decrement the value of +.IR shm_nattch +in the data structure associated with the shared memory ID of the +attached shared memory segment and return 0. Also, the +.IR shm_dtime +timestamp shall be set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +Otherwise, the shared memory segment shall not be detached, +\fIshmdt\fR() +shall return \-1, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIshmdt\fR() +function shall fail if: +.TP +.BR EINVAL +The value of +.IR shmaddr +is not the data segment start address of a shared memory segment. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmget\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/shmget.3p b/upstream/archlinux/man3p/shmget.3p new file mode 100644 index 00000000..feed7123 --- /dev/null +++ b/upstream/archlinux/man3p/shmget.3p @@ -0,0 +1,185 @@ +'\" et +.TH SHMGET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +shmget +\(em get an XSI shared memory segment +.SH SYNOPSIS +.LP +.nf +#include +.P +int shmget(key_t \fIkey\fP, size_t \fIsize\fP, int \fIshmflg\fP); +.fi +.SH DESCRIPTION +The +\fIshmget\fR() +function operates on XSI shared memory (see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object"). +It is unspecified whether this function interoperates with the +realtime interprocess communication facilities defined in +.IR "Section 2.8" ", " "Realtime". +.P +The +\fIshmget\fR() +function shall return the shared memory identifier associated with +.IR key . +.P +A shared memory identifier, associated data structure, and shared +memory segment of at least +.IR size +bytes (see +.IR ) +are created for +.IR key +if one of the following is true: +.IP " *" 4 +The argument +.IR key +is equal to IPC_PRIVATE. +.IP " *" 4 +The argument +.IR key +does not already have a shared memory identifier associated with it and +(\fIshmflg\fP &IPC_CREAT) is non-zero. +.P +Upon creation, the data structure associated with the new shared memory +identifier shall be initialized as follows: +.IP " *" 4 +The values of +.IR shm_perm.cuid , +.IR shm_perm.uid , +.IR shm_perm.cgid , +and +.IR shm_perm.gid +are set to the effective user ID and effective group ID, +respectively, of the calling process. +.IP " *" 4 +The low-order nine bits of +.IR shm_perm.mode +are set to the low-order nine bits of +.IR shmflg . +.IP " *" 4 +The value of +.IR shm_segsz +is set to the value of +.IR size . +.IP " *" 4 +The values of +.IR shm_lpid , +.IR shm_nattch , +.IR shm_atime , +and +.IR shm_dtime +are set to 0. +.IP " *" 4 +The value of +.IR shm_ctime +is set to the current time, as described in +.IR "Section 2.7.1" ", " "IPC General Description". +.P +When the shared memory segment is created, it shall be initialized +with all zero values. +.SH "RETURN VALUE" +Upon successful completion, +\fIshmget\fR() +shall return a non-negative integer, namely a shared memory identifier; +otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIshmget\fR() +function shall fail if: +.TP +.BR EACCES +A shared memory identifier exists for +.IR key +but operation permission as specified by the low-order nine bits of +.IR shmflg +would not be granted; see +.IR "Section 2.7" ", " "XSI Interprocess Communication". +.TP +.BR EEXIST +A shared memory identifier exists for the argument +.IR key +but (\fIshmflg\fR &IPC_CREAT) &&(\fIshmflg\fR &IPC_EXCL) is non-zero. +.TP +.BR EINVAL +A shared memory segment is to be created and the value of size is +less than the system-imposed minimum or greater than the +system-imposed maximum. +.TP +.BR EINVAL +No shared memory segment is to be created and a shared memory +segment exists for +.IR key +but the size of the segment associated with it is less than +.IR size . +.TP +.BR ENOENT +A shared memory identifier does not exist for the argument +.IR key +and (\fIshmflg\fP &IPC_CREAT) is 0. +.TP +.BR ENOMEM +A shared memory identifier and associated shared memory segment are to +be created, but the amount of available physical memory is not +sufficient to fill the request. +.TP +.BR ENOSPC +A shared memory identifier is to be created, but the system-imposed +limit on the maximum number of allowed shared memory identifiers +system-wide would be exceeded. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The POSIX Realtime Extension defines alternative interfaces for interprocess +communication. Application developers who need to use IPC should +design their applications so that modules using the IPC routines +described in +.IR "Section 2.7" ", " "XSI Interprocess Communication" +can be easily modified to use the alternative interfaces. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.7" ", " "XSI Interprocess Communication", +.IR "Section 2.8" ", " "Realtime", +.IR "\fIftok\fR\^(\|)", +.IR "\fIshmat\fR\^(\|)", +.IR "\fIshmctl\fR\^(\|)", +.IR "\fIshmdt\fR\^(\|)", +.IR "\fIshm_open\fR\^(\|)", +.IR "\fIshm_unlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.346" ", " "Shared Memory Object", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/shutdown.3p b/upstream/archlinux/man3p/shutdown.3p new file mode 100644 index 00000000..fc1ac57e --- /dev/null +++ b/upstream/archlinux/man3p/shutdown.3p @@ -0,0 +1,128 @@ +'\" et +.TH SHUTDOWN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +shutdown +\(em shut down socket send and receive operations +.SH SYNOPSIS +.LP +.nf +#include +.P +int shutdown(int \fIsocket\fP, int \fIhow\fP); +.fi +.SH DESCRIPTION +The +\fIshutdown\fR() +function shall cause all or part of a full-duplex connection on the +socket associated with the file descriptor +.IR socket +to be shut down. +.P +The +\fIshutdown\fR() +function takes the following arguments: +.IP "\fIsocket\fR" 12 +Specifies the file descriptor of the socket. +.IP "\fIhow\fR" 12 +Specifies the type of shutdown. The values are as follows: +.RS 12 +.IP SHUT_RD 12 +Disables further receive operations. +.IP SHUT_WR 12 +Disables further send operations. +.IP SHUT_RDWR 12 +Disables further send and receive operations. +.RE +.P +The +\fIshutdown\fR() +function disables subsequent send and/or receive operations on a +socket, depending on the value of the +.IR how +argument. +.SH "RETURN VALUE" +Upon successful completion, +\fIshutdown\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIshutdown\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR socket +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR how +argument is invalid. +.TP +.BR ENOTCONN +The socket is not connected. +.TP +.BR ENOTSOCK +The +.IR socket +argument does not refer to a socket. +.P +The +\fIshutdown\fR() +function may fail if: +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +None. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendto\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIsocket\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigaction.3p b/upstream/archlinux/man3p/sigaction.3p new file mode 100644 index 00000000..a375bab9 --- /dev/null +++ b/upstream/archlinux/man3p/sigaction.3p @@ -0,0 +1,660 @@ +'\" et +.TH SIGACTION "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigaction +\(em examine and change a signal action +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigaction(int \fIsig\fP, const struct sigaction *restrict \fIact\fP, + struct sigaction *restrict \fIoact\fP); +.fi +.SH DESCRIPTION +The +\fIsigaction\fR() +function allows the calling process to examine and/or specify the +action to be associated with a specific signal. The argument +.IR sig +specifies the signal; acceptable values are defined in +.IR . +.P +The structure +.BR sigaction , +used to describe an action to be taken, is defined in the +.IR +header to include at least the following members: +.ad l +.TS +center box tab(!); +cB | cB | cB +lw(1.5i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +void(*) (int)!sa_handler!T{ +Pointer to a signal-catching function or one of the macros +SIG_IGN or SIG_DFL. +T} +sigset_t!sa_mask!T{ +Additional set of signals to be blocked during execution of +signal-catching function. +T} +int!sa_flags!T{ +Special flags to affect behavior of signal. +T} +T{ +void(*) (int, +.br +\0\0siginfo_t *, void *) +T}!sa_sigaction!Pointer to a signal-catching function. +.TE +.ad b +.P +The storage occupied by +.IR sa_handler +and +.IR sa_sigaction +may overlap, and a conforming application shall not use both +simultaneously. +.P +If the argument +.IR act +is not a null pointer, it points to a structure specifying the action +to be associated with the specified signal. If the argument +.IR oact +is not a null pointer, the action previously associated with the signal +is stored in the location pointed to by the argument +.IR oact . +If the argument +.IR act +is a null pointer, signal handling is unchanged; thus, the call can be +used to enquire about the current handling of a given signal. The +SIGKILL and SIGSTOP signals shall not be added to the signal +mask using this mechanism; this restriction shall be enforced by the +system without causing an error to be indicated. +.P +If the SA_SIGINFO flag (see below) is cleared in the +.IR sa_flags +field of the +.BR sigaction +structure, the +.IR sa_handler +field identifies the action to be associated with the specified signal. +If the SA_SIGINFO flag is set in the +.IR sa_flags +field, the +.IR sa_sigaction +field specifies a signal-catching function. +.P +The +.IR sa_flags +field can be used to modify the behavior of the specified signal. +.P +The following flags, defined in the +.IR +header, can be set in +.IR sa_flags : +.IP SA_NOCLDSTOP 14 +Do not generate SIGCHLD when children stop +or stopped children continue. +.RS 14 +.P +If +.IR sig +is SIGCHLD and the SA_NOCLDSTOP flag is not set in +.IR sa_flags , +and the implementation supports the SIGCHLD signal, then a SIGCHLD +signal shall be generated for the calling process whenever any of its +child processes stop +and a SIGCHLD signal may be generated for the calling +process whenever any of its stopped child processes are continued. +If +.IR sig +is SIGCHLD and the SA_NOCLDSTOP flag is set in +.IR sa_flags , +then the implementation shall not generate a SIGCHLD signal in this +way. +.RE +.IP SA_ONSTACK 14 +If set and an alternate signal stack has been declared with +\fIsigaltstack\fR(), +the signal shall be delivered to the calling process on that stack. +Otherwise, the signal shall be delivered on the current stack. +.IP SA_RESETHAND 14 +If set, the disposition of the signal shall be reset to SIG_DFL and the +SA_SIGINFO flag shall be cleared on entry to the signal handler. +.RS 14 +.TP 10 +.BR Note: +SIGILL and SIGTRAP cannot be automatically reset when delivered; the +system silently enforces this restriction. +.P +Otherwise, the disposition of the signal shall not be modified on entry +to the signal handler. +.P +In addition, if this flag is set, +\fIsigaction\fR() +may behave as if the SA_NODEFER flag were also set. +.RE +.IP SA_RESTART 14 +This flag affects the behavior of interruptible functions; that is, +those specified to fail with +.IR errno +set to +.BR [EINTR] . +If set, and a function specified as interruptible is interrupted by +this signal, the function shall restart and shall not fail with +.BR [EINTR] +unless otherwise specified. If an interruptible function which uses a +timeout is restarted, the duration of the timeout following the restart +is set to an unspecified value that does not exceed the original +timeout value. If the flag is not set, interruptible functions +interrupted by this signal shall fail with +.IR errno +set to +.BR [EINTR] . +.IP SA_SIGINFO 14 +If cleared and the signal is caught, the signal-catching function +shall be entered as: +.RS 14 +.sp +.RS 4 +.nf + +void func(int \fIsigno\fP); +.fi +.P +.RE +.P +where +.IR signo +is the only argument to the signal-catching function. In this case, the +application shall use the +.IR sa_handler +member to describe the signal-catching function and the application +shall not modify the +.IR sa_sigaction +member. +.P +If SA_SIGINFO is set and the signal is caught, the signal-catching +function shall be entered as: +.sp +.RS 4 +.nf + +void func(int \fIsigno\fP, siginfo_t *\fIinfo\fP, void *\fIcontext\fP); +.fi +.P +.RE +.P +where two additional arguments are passed to the signal-catching +function. The second argument shall point to an object of type +.BR siginfo_t +explaining the reason why the signal was generated; the third argument +can be cast to a pointer to an object of type +.BR ucontext_t +to refer to the receiving thread's context that was interrupted when +the signal was delivered. In this case, the application shall use the +.IR sa_sigaction +member to describe the signal-catching function and the application +shall not modify the +.IR sa_handler +member. +.P +The +.IR si_signo +member contains the system-generated signal number. +.P +The +.IR si_errno +member may contain implementation-defined additional error +information; if non-zero, it contains an error number identifying the +condition that caused the signal to be generated. +.P +The +.IR si_code +member contains a code identifying the cause of the signal, as +described in +.IR "Section 2.4.3" ", " "Signal Actions". +.RE +.IP SA_NOCLDWAIT 14 +If +.IR sig +does not equal SIGCHLD, the behavior is unspecified. Otherwise, the +behavior of the SA_NOCLDWAIT flag is as specified in +.IR "Consequences of Process Termination". +.IP SA_NODEFER 14 +If set and +.IR sig +is caught, +.IR sig +shall not be added to the thread's signal mask on entry to the signal +handler unless it is included in +.IR sa_mask . +Otherwise, +.IR sig +shall always be added to the thread's signal mask on entry to the +signal handler. +.P +When a signal is caught by a signal-catching function installed by +\fIsigaction\fR(), +a new signal mask is calculated and installed for the duration of the +signal-catching function (or until a call to either +\fIsigprocmask\fR() +or +\fIsigsuspend\fR() +is made). This mask is formed by taking the union of the current +signal mask and the value of the +.IR sa_mask +for the signal being delivered, and unless SA_NODEFER or +SA_RESETHAND is set, +then including the signal being delivered. If and when the user's +signal handler returns normally, the original signal mask is restored. +.P +Once an action is installed for a specific signal, it shall remain +installed until another action is explicitly requested (by another +call to +\fIsigaction\fR()), +until the SA_RESETHAND flag causes resetting of the handler, +or until one of the +.IR exec +functions is called. +.P +If the previous action for +.IR sig +had been established by +\fIsignal\fR(), +the values of the fields returned in the structure pointed to by +.IR oact +are unspecified, and in particular +.IR oact ->\c +.IR sa_handler +is not necessarily the same value passed to +\fIsignal\fR(). +However, if a pointer to the same structure or a copy thereof is passed +to a subsequent call to +\fIsigaction\fR() +via the +.IR act +argument, handling of the signal shall be as if the original call to +\fIsignal\fR() +were repeated. +.P +If +\fIsigaction\fR() +fails, no new signal handler is installed. +.P +It is unspecified whether an attempt to set the action for a signal +that cannot be caught or ignored to SIG_DFL is ignored or causes an +error to be returned with +.IR errno +set to +.BR [EINVAL] . +.P +If SA_SIGINFO is not set in +.IR sa_flags , +then the disposition of subsequent occurrences of +.IR sig +when it is already pending is implementation-defined; the +signal-catching function shall be invoked with a single argument. +If SA_SIGINFO is set in +.IR sa_flags , +then subsequent occurrences of +.IR sig +generated by +\fIsigqueue\fR() +or as a result of any signal-generating function that supports the +specification of an application-defined value (when +.IR sig +is already pending) shall be queued in FIFO order until delivered or +accepted; the signal-catching function shall be invoked with three +arguments. The application specified value is passed to the +signal-catching function as the +.IR si_value +member of the +.BR siginfo_t +structure. +.P +The result of the use of +\fIsigaction\fR() +and a +\fIsigwait\fR() +function concurrently within a process on the same signal is +unspecified. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigaction\fR() +shall return 0; otherwise, \-1 shall be returned, +.IR errno +shall be set to indicate the error, and no new signal-catching function +shall be installed. +.br +.SH ERRORS +The +\fIsigaction\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is not a valid signal number or an attempt is made to catch a +signal that cannot be caught or ignore a signal that cannot be ignored. +.P +The +\fIsigaction\fR() +function may fail if: +.TP +.BR EINVAL +An attempt was made to set the action to SIG_DFL for a signal that +cannot be caught or ignored (or both). +.P +In addition, on systems that do not support the XSI option, the +\fIsigaction\fR() +function may fail if the SA_SIGINFO flag is set in the +.IR sa_flags +field of the +.BR sigaction +structure for a signal not in the range SIGRTMIN to SIGRTMAX. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Establishing a Signal Handler" +.P +The following example demonstrates the use of +\fIsigaction\fR() +to establish a handler for the SIGINT signal. +.sp +.RS 4 +.nf + +#include +.P +static void handler(int signum) +{ + /* Take appropriate actions for signal delivery */ +} +.P +int main() +{ + struct sigaction sa; +.P + sa.sa_handler = handler; + sigemptyset(&sa.sa_mask); + sa.sa_flags = SA_RESTART; /* Restart functions if + interrupted by handler */ + if (sigaction(SIGINT, &sa, NULL) == -1) + /* Handle error */; +.P + /* Further code */ +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIsigaction\fR() +function supersedes the +\fIsignal\fR() +function, and should be used in preference. In particular, +\fIsigaction\fR() +and +\fIsignal\fR() +should not be used in the same process to control the same signal. +The behavior of async-signal-safe functions, as defined in their +respective DESCRIPTION sections, is as specified by this volume of POSIX.1\(hy2017, regardless +of invocation from a signal-catching function. This is the only intended +meaning of the statement that async-signal-safe functions may be used in +signal-catching functions without restrictions. Applications must still +consider all effects of such functions on such things as data structures, +files, and process state. In particular, application developers need +to consider the restrictions on interactions when interrupting +\fIsleep\fR() +and interactions among multiple handles for a file description. The +fact that any specific function is listed as async-signal-safe does not +necessarily mean that invocation of that function from a +signal-catching function is recommended. +.P +In order to prevent errors arising from interrupting non-async-signal-safe +function calls, applications should protect calls to these functions +either by blocking the appropriate signals or through the use of some +programmatic semaphore (see +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +and so on). Note in particular that even the ``safe'' functions may +modify +.IR errno ; +the signal-catching function, if not executing as an independent +thread, should save and restore its value in order to avoid the +possibility that delivery of a signal in between an error return +from a function that sets +.IR errno +and the subsequent examination of +.IR errno +could result in the signal-catching function changing the value of +.IR errno . +Naturally, the same principles apply to the async-signal-safety of +application routines and asynchronous data access. Note that +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +are not in the list of async-signal-safe functions. This is because +the code executing after +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +can call any unsafe functions with the same danger as calling those +unsafe functions directly from the signal handler. Applications that +use +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +from within signal handlers require rigorous protection in order to be +portable. Many of the other functions that are excluded from the list +are traditionally implemented using either +\fImalloc\fR() +or +\fIfree\fR() +functions or the standard I/O library, both of which traditionally +use data structures in a non-async-signal-safe manner. Since any +combination of different functions using a common data structure can +cause async-signal-safety problems, this volume of POSIX.1\(hy2017 does not define the behavior +when any unsafe function is called in a signal handler that interrupts +an unsafe function. +.P +Usually, the signal is executed on the stack that was in effect before +the signal was delivered. An alternate stack may be specified to +receive a subset of the signals being caught. +.P +When the signal handler returns, the receiving thread resumes +execution at the point it was interrupted unless the signal handler +makes other arrangements. If +\fIlongjmp\fR() +or +\fI_longjmp\fR() +is used to leave the signal handler, then the signal mask must be +explicitly restored. +.P +This volume of POSIX.1\(hy2017 defines the third argument of a signal handling function when +SA_SIGINFO is set as a +.BR "void *" +instead of a +.BR "ucontext_t *" , +but without requiring type checking. New applications should +explicitly cast the third argument of the signal handling function to +.BR "ucontext_t *" . +.P +The BSD optional four argument signal handling function is not +supported by this volume of POSIX.1\(hy2017. The BSD declaration would be: +.sp +.RS 4 +.nf + +void handler(int \fIsig\fP, int \fIcode\fP, struct sigcontext *\fIscp\fP, + char *\fIaddr\fP); +.fi +.P +.RE +.P +where +.IR sig +is the signal number, +.IR code +is additional information on certain signals, +.IR scp +is a pointer to the +.BR sigcontext +structure, and +.IR addr +is additional address information. Much the same information is +available in the objects pointed to by the second argument of the +signal handler specified when SA_SIGINFO is set. +.P +Since the +\fIsigaction\fR() +function is allowed but not required to set SA_NODEFER when the +application sets the SA_RESETHAND flag, applications which depend on the +SA_RESETHAND functionality for the newly installed signal handler must +always explicitly set SA_NODEFER when they set SA_RESETHAND in order to +be portable. +.P +See also the rationale for Realtime Signal Generation and Delivery in +the Rationale (Informative) volume of POSIX.1\(hy2017, +.IR "Section B.2.4.2" ", " "Signal Generation and Delivery". +.SH RATIONALE +Although this volume of POSIX.1\(hy2017 requires that signals that cannot be ignored +shall not be added to the signal mask when a signal-catching function +is entered, there is no explicit requirement that subsequent calls to +\fIsigaction\fR() +reflect this in the information returned in the +.IR oact +argument. In other words, if SIGKILL +is included in the +.IR sa_mask +field of +.IR act , +it is unspecified whether or not a subsequent call to +\fIsigaction\fR() +returns with SIGKILL included in the +.IR sa_mask +field of +.IR oact . +.P +The SA_NOCLDSTOP +flag, when supplied in the +.IR act ->\c +.IR sa_flags +parameter, allows overloading SIGCHLD with the System V +semantics that each SIGCLD +signal indicates a single terminated child. Most conforming applications +that catch SIGCHLD are expected to install signal-catching functions +that repeatedly call the +\fIwaitpid\fR() +function with the WNOHANG +flag set, acting on each child for which status is returned, until +\fIwaitpid\fR() +returns zero. If stopped children are not of interest, the use of the +SA_NOCLDSTOP +flag can prevent the overhead from invoking the signal-catching routine +when they stop. +.P +Some historical implementations also define other mechanisms for +stopping processes, such as the +\fIptrace\fR() +function. These implementations usually do not generate a SIGCHLD +signal when processes stop due to this mechanism; however, that is +beyond the scope of this volume of POSIX.1\(hy2017. +.P +This volume of POSIX.1\(hy2017 requires that calls to +\fIsigaction\fR() +that supply a NULL +.IR act +argument succeed, even in the case of signals that cannot be caught or +ignored (that is, SIGKILL +or SIGSTOP). +The System V +\fIsignal\fR() +and BSD +\fIsigvec\fR() +functions return +.BR [EINVAL] +in these cases and, in this respect, their behavior varies from +\fIsigaction\fR(). +.P +This volume of POSIX.1\(hy2017 requires that +\fIsigaction\fR() +properly save and restore a signal action set up by the ISO\ C standard +\fIsignal\fR() +function. However, there is no guarantee that the reverse is true, nor +could there be given the greater amount of information conveyed by the +.BR sigaction +structure. Because of this, applications should avoid using both +functions for the same signal in the same process. Since this cannot +always be avoided in case of general-purpose library routines, they +should always be implemented with +\fIsigaction\fR(). +.P +It was intended that the +\fIsignal\fR() +function should be implementable as a library routine using +\fIsigaction\fR(). +.P +The POSIX Realtime Extension extends the +\fIsigaction\fR() +function as specified by the POSIX.1\(hy1990 standard to allow the application to request +on a per-signal basis via an additional signal action flag that the +extra parameters, including the application-defined signal value, if +any, be passed to the signal-catching function. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fI_Exit\fR\^(\|)", +.IR "\fIkill\fR\^(\|)", +.IR "\fI_longjmp\fR\^(\|)", +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsemget\fR\^(\|)", +.IR "\fIsem_init\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigaltstack\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigaddset.3p b/upstream/archlinux/man3p/sigaddset.3p new file mode 100644 index 00000000..1b85861e --- /dev/null +++ b/upstream/archlinux/man3p/sigaddset.3p @@ -0,0 +1,105 @@ +'\" et +.TH SIGADDSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigaddset +\(em add a signal to a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigaddset(sigset_t *\fIset\fP, int \fIsigno\fP); +.fi +.SH DESCRIPTION +The +\fIsigaddset\fR() +function adds the individual signal specified by the +.IR signo +to the signal set pointed to by +.IR set . +.P +Applications shall call either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +at least once for each object of type +.BR sigset_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of +\fIpthread_sigmask\fR(), +\fIsigaction\fR(), +\fIsigaddset\fR(), +\fIsigdelset\fR(), +\fIsigismember\fR(), +\fIsigpending\fR(), +\fIsigprocmask\fR(), +\fIsigsuspend\fR(), +\fIsigtimedwait\fR(), +\fIsigwait\fR(), +or +\fIsigwaitinfo\fR(), +the results are undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigaddset\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigaddset\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR signo +argument is an invalid or unsupported signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigaltstack.3p b/upstream/archlinux/man3p/sigaltstack.3p new file mode 100644 index 00000000..f9aac8f6 --- /dev/null +++ b/upstream/archlinux/man3p/sigaltstack.3p @@ -0,0 +1,183 @@ +'\" et +.TH SIGALTSTACK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigaltstack +\(em set and get signal alternate stack context +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigaltstack(const stack_t *restrict \fIss\fP, stack_t *restrict \fIoss\fP); +.fi +.SH DESCRIPTION +The +\fIsigaltstack\fR() +function allows a process to define and examine the state of an +alternate stack for signal handlers for the current thread. Signals +that have been explicitly declared to execute on the alternate stack +shall be delivered on the alternate stack. +.P +If +.IR ss +is not a null pointer, it points to a +.BR stack_t +structure that specifies the alternate signal stack that shall take +effect upon return from +\fIsigaltstack\fR(). +The +.IR ss_flags +member specifies the new stack state. If it is set to SS_DISABLE, the +stack is disabled and +.IR ss_sp +and +.IR ss_size +are ignored. Otherwise, the stack shall be enabled, and the +.IR ss_sp +and +.IR ss_size +members specify the new address and size of the stack. +.P +The range of addresses starting at +.IR ss_sp +up to but not including +.IR ss_sp +\c +.IR ss_size +is available to the implementation for use as the stack. This function +makes no assumptions regarding which end is the stack base and in which +direction the stack grows as items are pushed. +.P +If +.IR oss +is not a null pointer, upon successful completion it shall point to a +.BR stack_t +structure that specifies the alternate signal stack that was in effect +prior to the call to +\fIsigaltstack\fR(). +The +.IR ss_sp +and +.IR ss_size +members specify the address and size of that stack. The +.IR ss_flags +member specifies the stack's state, and may contain one of the +following values: +.IP SS_ONSTACK 12 +The process is currently executing on the alternate signal stack. +Attempts to modify the alternate signal stack while the process is +executing on it fail. This flag shall not be modified by processes. +.IP SS_DISABLE 12 +The alternate signal stack is currently disabled. +.P +The value SIGSTKSZ is a system default specifying the number of bytes +that would be used to cover the usual case when manually allocating an +alternate stack area. The value MINSIGSTKSZ is defined to be the +minimum stack size for +a signal handler. In computing an alternate stack size, a program +should add that amount to its stack requirements to allow for the +system implementation overhead. The constants SS_ONSTACK, SS_DISABLE, +SIGSTKSZ, and MINSIGSTKSZ are +defined in +.IR . +.P +After a successful call to one of the +.IR exec +functions, there are no alternate signal stacks in the new process +image. +.P +In some implementations, a signal (whether or not indicated to execute +on the alternate stack) shall always execute on the alternate stack if +it is delivered while another signal is being caught using the +alternate stack. +.P +Use of this function by library threads that are not bound to +kernel-scheduled entities results in undefined behavior. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigaltstack\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigaltstack\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR ss +argument is not a null pointer, and the +.IR ss_flags +member pointed to by +.IR ss +contains flags other than SS_DISABLE. +.TP +.BR ENOMEM +The size of the alternate stack area is less than MINSIGSTKSZ. +.TP +.BR EPERM +An attempt was made to modify an active stack. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Allocating Memory for an Alternate Stack" +.P +The following example illustrates a method for allocating memory for an +alternate stack. +.sp +.RS 4 +.nf + +#include +\&... +if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) + /* Error return. */ +sigstk.ss_size = SIGSTKSZ; +sigstk.ss_flags = 0; +if (sigaltstack(&sigstk,(stack_t *)0) < 0) + perror("sigaltstack"); +.fi +.P +.RE +.SH "APPLICATION USAGE" +On some implementations, stack space is automatically extended as +needed. On those implementations, automatic extension is typically not +available for an alternate stack. If the stack overflows, the +behavior is undefined. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigdelset.3p b/upstream/archlinux/man3p/sigdelset.3p new file mode 100644 index 00000000..86c27c62 --- /dev/null +++ b/upstream/archlinux/man3p/sigdelset.3p @@ -0,0 +1,106 @@ +'\" et +.TH SIGDELSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigdelset +\(em delete a signal from a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigdelset(sigset_t *\fIset\fP, int \fIsigno\fP); +.fi +.SH DESCRIPTION +The +\fIsigdelset\fR() +function deletes the individual signal specified by +.IR signo +from the signal set pointed to by +.IR set . +.P +Applications should call either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +at least once for each object of type +.BR sigset_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of +\fIpthread_sigmask\fR(), +\fIsigaction\fR(), +\fIsigaddset\fR(), +\fIsigdelset\fR(), +\fIsigismember\fR(), +\fIsigpending\fR(), +\fIsigprocmask\fR(), +\fIsigsuspend\fR(), +\fIsigtimedwait\fR(), +\fIsigwait\fR(), +or +\fIsigwaitinfo\fR(), +the results are undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigdelset\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigdelset\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR signo +argument is not a valid signal number, or is an unsupported signal +number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigemptyset.3p b/upstream/archlinux/man3p/sigemptyset.3p new file mode 100644 index 00000000..f1aac401 --- /dev/null +++ b/upstream/archlinux/man3p/sigemptyset.3p @@ -0,0 +1,120 @@ +'\" et +.TH SIGEMPTYSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigemptyset +\(em initialize and empty a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigemptyset(sigset_t *\fIset\fP); +.fi +.SH DESCRIPTION +The +\fIsigemptyset\fR() +function initializes the signal set pointed to by +.IR set , +such that all signals defined in POSIX.1\(hy2008 are excluded. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigemptyset\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The implementation of the +\fIsigemptyset\fR() +(or +\fIsigfillset\fR()) +function could quite trivially clear (or set) all the bits in the +signal set. Alternatively, it would be reasonable to initialize part +of the structure, such as a version field, to permit +binary-compatibility between releases where the size of the set +varies. For such reasons, either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +must be called prior to any other use of the signal set, even if such +use is read-only (for example, as an argument to +\fIsigpending\fR()). +This function is not intended for dynamic allocation. +.P +The +\fIsigfillset\fR() +and +\fIsigemptyset\fR() +functions require that the resulting signal set include (or exclude) +all the signals defined in this volume of POSIX.1\(hy2017. Although it is outside the scope of +\&this volume of POSIX.1\(hy2017 to place this requirement on signals that are implemented as +extensions, it is recommended that implementation-defined signals +also be affected by these functions. However, there may be a good +reason for a particular signal not to be affected. For example, +blocking or ignoring an implementation-defined signal may have +undesirable side-effects, whereas the default action for that signal is +harmless. In such a case, it would be preferable for such a signal to +be excluded from the signal set returned by +\fIsigfillset\fR(). +.P +In early proposals there was no distinction between invalid and +unsupported signals (the names of optional signals that were not +supported by an implementation were not defined by that +implementation). The +.BR [EINVAL] +error was thus specified as a required error for invalid signals. With +that distinction, it is not necessary to require implementations of +these functions to determine whether an optional signal is actually +supported, as that could have a significant performance impact for +little value. The error could have been required for invalid signals +and optional for unsupported signals, but this seemed unnecessarily +complex. Thus, the error is optional in both cases. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigfillset.3p b/upstream/archlinux/man3p/sigfillset.3p new file mode 100644 index 00000000..23f1926e --- /dev/null +++ b/upstream/archlinux/man3p/sigfillset.3p @@ -0,0 +1,75 @@ +'\" et +.TH SIGFILLSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigfillset +\(em initialize and fill a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigfillset(sigset_t *\fIset\fP); +.fi +.SH DESCRIPTION +The +\fIsigfillset\fR() +function shall initialize the signal set pointed to by +.IR set , +such that all signals defined in this volume of POSIX.1\(hy2017 are included. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigfillset\fR() +shall return 0; otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIsigemptyset\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sighold.3p b/upstream/archlinux/man3p/sighold.3p new file mode 100644 index 00000000..6ed9ad10 --- /dev/null +++ b/upstream/archlinux/man3p/sighold.3p @@ -0,0 +1,257 @@ +'\" et +.TH SIGHOLD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sighold, +sigignore, +sigpause, +sigrelse, +sigset +\(em signal management +.SH SYNOPSIS +.LP +.nf +#include +.P +int sighold(int \fIsig\fP); +int sigignore(int \fIsig\fP); +int sigpause(int \fIsig\fP); +int sigrelse(int \fIsig\fP); +void (*sigset(int \fIsig\fP, void (*\fIdisp\fP)(int)))(int); +.fi +.SH DESCRIPTION +Use of any of these functions is unspecified in a multi-threaded +process. +.P +The +\fIsighold\fR(), +\fIsigignore\fR(), +\fIsigpause\fR(), +\fIsigrelse\fR(), +and +\fIsigset\fR() +functions provide simplified signal management. +.P +The +\fIsigset\fR() +function shall modify signal dispositions. The +.IR sig +argument specifies the signal, which may be any signal except SIGKILL +and SIGSTOP. The +.IR disp +argument specifies the signal's disposition, which may be SIG_DFL, +SIG_IGN, or the address of a signal handler. If +\fIsigset\fR() +is used, and +.IR disp +is the address of a signal handler, the system shall add +.IR sig +to the signal mask of the calling process before executing the signal +handler; when the signal handler returns, the system shall restore the +signal mask of the calling process to its state prior to the delivery +of the signal. In addition, if +\fIsigset\fR() +is used, and +.IR disp +is equal to SIG_HOLD, +.IR sig +shall be added to the +signal mask of the calling process and +.IR sig 's +disposition shall remain unchanged. If +\fIsigset\fR() +is used, and +.IR disp +is not equal to SIG_HOLD, +.IR sig +shall be removed from the signal mask of the calling process. +.P +The +\fIsighold\fR() +function shall add +.IR sig +to the signal mask of the calling process. +.P +The +\fIsigrelse\fR() +function shall remove +.IR sig +from the signal mask of the calling process. +.P +The +\fIsigignore\fR() +function shall set the disposition of +.IR sig +to SIG_IGN. +.P +The +\fIsigpause\fR() +function shall remove +.IR sig +from the signal mask of the calling process and suspend the calling process +until a signal is received. The +\fIsigpause\fR() +function shall restore the signal mask of the process to its original +state before returning. +.P +If the action for the SIGCHLD signal is set to SIG_IGN, child processes +of the +calling processes shall not be transformed into zombie processes when +they terminate. If the calling process subsequently waits for its +children, and the process has no unwaited-for children that were +transformed into zombie processes, it shall block until all of its +children terminate, and +\fIwait\fR(), +\fIwaitid\fR(), +and +\fIwaitpid\fR() +shall fail and set +.IR errno +to +.BR [ECHILD] . +.SH "RETURN VALUE" +Upon successful completion, +\fIsigset\fR() +shall return SIG_HOLD if the signal had been blocked and the signal's +previous disposition if it had not been blocked. Otherwise, SIG_ERR +shall be returned and +.IR errno +set to indicate the error. +.P +The +\fIsigpause\fR() +function shall suspend execution of the thread until a signal is +received, whereupon it shall return \-1 and set +.IR errno +to +.BR [EINTR] . +.P +For all other functions, upon successful completion, 0 shall be returned. +Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is an illegal signal number. +.P +The +\fIsigset\fR() +and +\fIsigignore\fR() +functions shall fail if: +.TP +.BR EINVAL +An attempt is made to catch a signal that cannot be caught, or to +ignore a signal that cannot be ignored. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsigaction\fR() +function provides a more comprehensive and reliable mechanism for +controlling signals; new applications should use the +\fIsigaction\fR() +function instead of the obsolescent +\fIsigset\fR() +function. +.P +The +\fIsighold\fR() +function, in conjunction with +\fIsigrelse\fR() +or +\fIsigpause\fR(), +may be used to establish critical regions of code that require the +delivery of a signal to be temporarily deferred. For broader +portability, the +\fIpthread_sigmask\fR() +or +\fIsigprocmask\fR() +functions should be used instead of the obsolescent +\fIsighold\fR() +and +\fIsigrelse\fR() +functions. +.P +For broader portability, the +\fIsigsuspend\fR() +function should be used instead of the obsolescent +\fIsigpause\fR() +function. +.SH RATIONALE +Each of these historic functions has a direct analog in the other +functions which are required to be per-thread and thread-safe (aside +from +\fIsigprocmask\fR(), +which is replaced by +\fIpthread_sigmask\fR()). +The +\fIsigset\fR() +function can be implemented as a simple wrapper for +\fIsigaction\fR(). +The +\fIsighold\fR() +function is equivalent to +\fIsigprocmask\fR() +or +\fIpthread_sigmask\fR() +with SIG_BLOCK set. The +\fIsigignore\fR() +function is equivalent to +\fIsigaction\fR() +with SIG_IGN set. The +\fIsigpause\fR() +function is equivalent to +\fIsigsuspend\fR(). +The +\fIsigrelse\fR() +function is equivalent to +\fIsigprocmask\fR() +or +\fIpthread_sigmask\fR() +with SIG_UNBLOCK set. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/siginterrupt.3p b/upstream/archlinux/man3p/siginterrupt.3p new file mode 100644 index 00000000..f8647a64 --- /dev/null +++ b/upstream/archlinux/man3p/siginterrupt.3p @@ -0,0 +1,101 @@ +'\" et +.TH SIGINTERRUPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +siginterrupt +\(em allow signals to interrupt functions +.SH SYNOPSIS +.LP +.nf +#include +.P +int siginterrupt(int \fIsig\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIsiginterrupt\fR() +function shall change the restart behavior when a function is +interrupted by the specified signal. The function +\fIsiginterrupt\fP(\fIsig\fP, \fIflag\fP) has an effect as if +implemented as: +.sp +.RS 4 +.nf + +int siginterrupt(int sig, int flag) { + int ret; + struct sigaction act; +.P + (void) sigaction(sig, NULL, &act); + if (flag) + act.sa_flags &= \(tiSA_RESTART; + else + act.sa_flags |= SA_RESTART; + ret = sigaction(sig, &act, NULL); + return ret; +} +.fi +.P +.RE +.SH "RETURN VALUE" +Upon successful completion, +\fIsiginterrupt\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsiginterrupt\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is not a valid signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsiginterrupt\fR() +function supports programs written to historical system interfaces. +Applications should use the +\fIsigaction\fR() +with the SA_RESTART flag instead of the obsolescent +\fIsiginterrupt\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIsigaction\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigismember.3p b/upstream/archlinux/man3p/sigismember.3p new file mode 100644 index 00000000..0bc53d4e --- /dev/null +++ b/upstream/archlinux/man3p/sigismember.3p @@ -0,0 +1,107 @@ +'\" et +.TH SIGISMEMBER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigismember +\(em test for a signal in a signal set +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigismember(const sigset_t *\fIset\fP, int \fIsigno\fP); +.fi +.SH DESCRIPTION +The +\fIsigismember\fR() +function shall test whether the signal specified by +.IR signo +is a member of the set pointed to by +.IR set . +.P +Applications should call either +\fIsigemptyset\fR() +or +\fIsigfillset\fR() +at least once for each object of type +.BR sigset_t +prior to any other use of that object. If such an object is not +initialized in this way, but is nonetheless supplied as an argument to +any of +\fIpthread_sigmask\fR(), +\fIsigaction\fR(), +\fIsigaddset\fR(), +\fIsigdelset\fR(), +\fIsigismember\fR(), +\fIsigpending\fR(), +\fIsigprocmask\fR(), +\fIsigsuspend\fR(), +\fIsigtimedwait\fR(), +\fIsigwait\fR(), +or +\fIsigwaitinfo\fR(), +the results are undefined. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigismember\fR() +shall return 1 if the specified signal is a member of the specified set, +or 0 if it is not. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigismember\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR signo +argument is not a valid signal number, or is an unsupported signal +number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/siglongjmp.3p b/upstream/archlinux/man3p/siglongjmp.3p new file mode 100644 index 00000000..3b2ea0b7 --- /dev/null +++ b/upstream/archlinux/man3p/siglongjmp.3p @@ -0,0 +1,108 @@ +'\" et +.TH SIGLONGJMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +siglongjmp +\(em non-local goto with signal handling +.SH SYNOPSIS +.LP +.nf +#include +.P +void siglongjmp(sigjmp_buf \fIenv\fP, int \fIval\fP); +.fi +.SH DESCRIPTION +The +\fIsiglongjmp\fR() +function shall be equivalent to the +\fIlongjmp\fR() +function, except as follows: +.IP " *" 4 +References to +\fIsetjmp\fR() +shall be equivalent to +\fIsigsetjmp\fR(). +.IP " *" 4 +The +\fIsiglongjmp\fR() +function shall restore the saved signal mask if and only if the +.IR env +argument was initialized by a call to +\fIsigsetjmp\fR() +with a non-zero +.IR savemask +argument. +.SH "RETURN VALUE" +After +\fIsiglongjmp\fR() +is completed, program execution shall continue as if the corresponding +invocation of +\fIsigsetjmp\fR() +had just returned the value specified by +.IR val . +The +\fIsiglongjmp\fR() +function shall not cause +\fIsigsetjmp\fR() +to return 0; if +.IR val +is 0, +\fIsigsetjmp\fR() +shall return the value 1. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The distinction between +\fIsetjmp\fR() +or +\fIlongjmp\fR() +and +\fIsigsetjmp\fR() +or +\fIsiglongjmp\fR() +is only significant for programs which use +\fIsigaction\fR(), +\fIsigprocmask\fR(), +or +\fIsigsuspend\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIlongjmp\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsetjmp\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/signal.3p b/upstream/archlinux/man3p/signal.3p new file mode 100644 index 00000000..366e0b7b --- /dev/null +++ b/upstream/archlinux/man3p/signal.3p @@ -0,0 +1,218 @@ +'\" et +.TH SIGNAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +signal +\(em signal management +.SH SYNOPSIS +.LP +.nf +#include +.P +void (*signal(int \fIsig\fP, void (*\fIfunc\fP)(int)))(int); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIsignal\fR() +function chooses one of three ways in which receipt of the signal +number +.IR sig +is to be subsequently handled. If the value of +.IR func +is SIG_DFL, default handling for that signal shall occur. +If the value of +.IR func +is SIG_IGN, the signal shall be ignored. +Otherwise, the application shall ensure that +.IR func +points to a function to be called when that signal occurs. An +invocation of such a function because of a signal, or (recursively) of +any further functions called by that invocation (other than functions +in the standard library), is called a ``signal handler''. +.P +When a signal occurs, and +.IR func +points to a function, it is implementation-defined whether the +equivalent of a: +.sp +.RS 4 +.nf + +signal(\fIsig\fP, SIG_DFL); +.fi +.P +.RE +.P +is executed or the implementation prevents some implementation-defined +set of signals (at least including +.IR sig ) +from occurring until the current signal handling has completed. (If the +value of +.IR sig +is SIGILL, the implementation may alternatively define that no action +is taken.) Next the equivalent of: +.sp +.RS 4 +.nf + +(*func)(sig); +.fi +.P +.RE +.P +is executed. If and when the function returns, if the value of +.IR sig +was SIGFPE, SIGILL, or SIGSEGV or any other implementation-defined +value corresponding to +a computational exception, the behavior is undefined. Otherwise, the +program shall resume execution at the point it was interrupted. The +ISO\ C standard places a restriction on applications relating to the use of +\fIraise\fR() +from signal handlers. +This restriction does not apply to POSIX applications, as POSIX.1\(hy2008 requires +\fIraise\fR() +to be async-signal-safe (see +.IR "Section 2.4.3" ", " "Signal Actions"). +.P +If the process is multi-threaded, +or if the process is single-threaded and a signal handler is +executed other than as the result of: +.IP " *" 4 +The process calling +\fIabort\fR(), +\fIraise\fR(), +\fIkill\fR(), +\fIpthread_kill\fR(), +or +\fIsigqueue\fR() +to generate a signal that is not blocked +.IP " *" 4 +A pending signal being unblocked and being delivered before the call +that unblocked it returns +.P +the behavior is undefined if the signal handler refers to any object +other than +.IR errno +with static storage duration other than by assigning a value to an +object declared as +.BR "volatile sig_atomic_t" , +or if the signal handler calls any function defined in this standard +other than +one of the functions listed in +.IR "Section 2.4" ", " "Signal Concepts". +.P +At program start-up, the equivalent of: +.sp +.RS 4 +.nf + +signal(\fIsig\fP, SIG_IGN); +.fi +.P +.RE +.P +is executed for some signals, and the equivalent of: +.sp +.RS 4 +.nf + +signal(\fIsig\fP, SIG_DFL); +.fi +.P +.RE +.P +is executed for all other signals +(see +.IR exec ). +.P +The +\fIsignal\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +If the request can be honored, +\fIsignal\fR() +shall return the value of +.IR func +for the most recent call to +\fIsignal\fR() +for the specified signal +.IR sig . +Otherwise, SIG_ERR shall be returned and a positive value shall +be stored in +.IR errno . +.SH ERRORS +The +\fIsignal\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR sig +argument is not a valid signal number or an attempt is made to catch a +signal that cannot be caught or ignore a signal that cannot be +ignored. +.P +The +\fIsignal\fR() +function may fail if: +.TP +.BR EINVAL +An attempt was made to set the action to SIG_DFL for a signal that +cannot be caught or ignored (or both). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsigaction\fR() +function provides a more comprehensive and reliable mechanism for +controlling signals; new applications should use +\fIsigaction\fR() +rather than +\fIsignal\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIexec\fR\^", +.IR "\fIpause\fR\^(\|)", +.IR "\fIraise\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/signbit.3p b/upstream/archlinux/man3p/signbit.3p new file mode 100644 index 00000000..bc7f2a21 --- /dev/null +++ b/upstream/archlinux/man3p/signbit.3p @@ -0,0 +1,72 @@ +'\" et +.TH SIGNBIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +signbit +\(em test sign +.SH SYNOPSIS +.LP +.nf +#include +.P +int signbit(real-floating \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIsignbit\fR() +macro shall determine whether the sign of its argument value is +negative. NaNs, zeros, and infinities have a sign bit. +.SH "RETURN VALUE" +The +\fIsignbit\fR() +macro shall return a non-zero value if and only if the sign of its +argument value is negative. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfpclassify\fR\^(\|)", +.IR "\fIisfinite\fR\^(\|)", +.IR "\fIisinf\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIisnormal\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/signgam.3p b/upstream/archlinux/man3p/signgam.3p new file mode 100644 index 00000000..d4763498 --- /dev/null +++ b/upstream/archlinux/man3p/signgam.3p @@ -0,0 +1,40 @@ +'\" et +.TH SIGNGAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +signgam +\(em log gamma function +.SH SYNOPSIS +.LP +.nf +#include +.P +extern int signgam; +.fi +.SH DESCRIPTION +Refer to +.IR "\fIlgamma\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigpause.3p b/upstream/archlinux/man3p/sigpause.3p new file mode 100644 index 00000000..40f280a7 --- /dev/null +++ b/upstream/archlinux/man3p/sigpause.3p @@ -0,0 +1,40 @@ +'\" et +.TH SIGPAUSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigpause +\(em remove a signal from the signal mask and suspend the thread +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigpause(int \fIsig\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsighold\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigpending.3p b/upstream/archlinux/man3p/sigpending.3p new file mode 100644 index 00000000..f300fb40 --- /dev/null +++ b/upstream/archlinux/man3p/sigpending.3p @@ -0,0 +1,74 @@ +'\" et +.TH SIGPENDING "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigpending +\(em examine pending signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigpending(sigset_t *\fIset\fP); +.fi +.SH DESCRIPTION +The +\fIsigpending\fR() +function shall store, in the location referenced by the +.IR set +argument, the set of signals that are blocked from delivery to the +calling thread and that are pending on the process or the calling +thread. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigpending\fR() +shall return 0; otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)", +.IR "\fIsigismember\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigprocmask.3p b/upstream/archlinux/man3p/sigprocmask.3p new file mode 100644 index 00000000..6be3a05b --- /dev/null +++ b/upstream/archlinux/man3p/sigprocmask.3p @@ -0,0 +1,41 @@ +'\" et +.TH SIGPROCMASK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigprocmask +\(em examine and change blocked signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigprocmask(int \fIhow\fP, const sigset_t *restrict \fIset\fP, + sigset_t *restrict \fIoset\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIpthread_sigmask\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigqueue.3p b/upstream/archlinux/man3p/sigqueue.3p new file mode 100644 index 00000000..3743dfcd --- /dev/null +++ b/upstream/archlinux/man3p/sigqueue.3p @@ -0,0 +1,190 @@ +'\" et +.TH SIGQUEUE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigqueue +\(em queue a signal to a process +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigqueue(pid_t \fIpid\fP, int \fIsigno\fP, union sigval \fIvalue\fP); +.fi +.SH DESCRIPTION +The +\fIsigqueue\fR() +function shall cause the signal specified by +.IR signo +to be sent with the value specified by +.IR value +to the process specified by +.IR pid . +If +.IR 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 +.IR pid . +.P +The conditions required for a process to have permission to queue a +signal to another process are the same as for the +\fIkill\fR() +function. +.P +The +\fIsigqueue\fR() +function shall return immediately. If SA_SIGINFO is set for +.IR signo +and if the resources were available to queue the signal, the signal +shall be queued and sent to the receiving process. If SA_SIGINFO is not +set for +.IR signo , +then +.IR signo +shall be sent at least once to the receiving process; it is unspecified +whether +.IR value +shall be sent to the receiving process as a result of this call. +.P +If the value of +.IR pid +causes +.IR signo +to be generated for the sending process, and if +.IR signo +is not blocked for the calling thread and if no other thread has +.IR signo +unblocked or is waiting in a +\fIsigwait\fR() +function for +.IR signo , +either +.IR signo +or at least the pending, unblocked signal shall be delivered to the +calling thread before the +\fIsigqueue\fR() +function returns. Should any multiple pending signals in the range +SIGRTMIN to +SIGRTMAX be selected for delivery, 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. +.SH "RETURN VALUE" +Upon successful completion, the specified signal shall have been +queued, and the +\fIsigqueue\fR() +function shall return a value of zero. Otherwise, the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigqueue\fR() +function shall fail if: +.TP +.BR EAGAIN +No resources are available to queue the signal. The process has already +queued +{SIGQUEUE_MAX} +signals that are still pending at the receiver(s), or a system-wide +resource limit has been exceeded. +.TP +.BR EINVAL +The value of the +.IR signo +argument is an invalid or unsupported signal number. +.TP +.BR EPERM +The process does not have appropriate privileges to send the signal +to the receiving process. +.TP +.BR ESRCH +The process +.IR pid +does not exist. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fIsigqueue\fR() +function allows an application to queue a realtime signal to itself or +to another process, specifying the application-defined value. This is +common practice in realtime applications on existing realtime systems. +It was felt that specifying another function in the +.IR sig .\|.\|. +name space already carved out for signals was preferable to extending +the interface to +\fIkill\fR(). +.P +Such a function became necessary when the put/get event function of +the message queues was removed. It should be noted that the +\fIsigqueue\fR() +function implies reduced performance in a security-conscious +implementation as the access permissions between the sender and +receiver have to be checked on each send when the +.IR pid +is resolved into a target process. Such access checks were necessary +only at message queue open in the previous interface. +.P +The standard developers required that +\fIsigqueue\fR() +have the same semantics with respect to the null signal as +\fIkill\fR(), +and that the same permission checking be used. But because of the +difficulty of implementing the ``broadcast'' semantic of +\fIkill\fR() +(for example, to process groups) and the interaction with resource +allocation, this semantic was not adopted. The +\fIsigqueue\fR() +function queues a signal to a single process specified by the +.IR pid +argument. +.P +The +\fIsigqueue\fR() +function can fail if the system has insufficient resources to queue the +signal. An explicit limit on the number of queued signals that a +process could send was introduced. While the limit is ``per-sender'', +\&this volume of POSIX.1\(hy2017 does not specify that the resources be part of the state +of the sender. This would require either that the sender be maintained +after exit until all signals that it had sent to other processes were +handled or that all such signals that had not yet been acted upon be +removed from the queue(s) of the receivers. This volume of POSIX.1\(hy2017 does not +preclude this behavior, but an implementation that allocated queuing +resources from a system-wide pool (with per-sender limits) and that +leaves queued signals pending after the sender exits is also +permitted. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.8.1" ", " "Realtime Signals" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigrelse.3p b/upstream/archlinux/man3p/sigrelse.3p new file mode 100644 index 00000000..2505fa23 --- /dev/null +++ b/upstream/archlinux/man3p/sigrelse.3p @@ -0,0 +1,42 @@ +'\" et +.TH SIGRELSE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigrelse, +sigset +\(em signal management +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigrelse(int \fIsig\fP); +void (*sigset(int \fIsig\fP, void (*\fIdisp\fP)(int)))(int); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsighold\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigsetjmp.3p b/upstream/archlinux/man3p/sigsetjmp.3p new file mode 100644 index 00000000..0fbcc94c --- /dev/null +++ b/upstream/archlinux/man3p/sigsetjmp.3p @@ -0,0 +1,157 @@ +'\" et +.TH SIGSETJMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigsetjmp +\(em set jump point for a non-local goto +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigsetjmp(sigjmp_buf \fIenv\fP, int \fIsavemask\fP); +.fi +.SH DESCRIPTION +The +\fIsigsetjmp\fR() +function shall be equivalent to the +\fIsetjmp\fR() +function, except as follows: +.IP " *" 4 +References to +\fIsetjmp\fR() +are equivalent to +\fIsigsetjmp\fR(). +.IP " *" 4 +References to +\fIlongjmp\fR() +are equivalent to +\fIsiglongjmp\fR(). +.IP " *" 4 +If the value of the +.IR savemask +argument is not 0, +\fIsigsetjmp\fR() +shall also save the current signal mask of the calling thread as part +of the calling environment. +.SH "RETURN VALUE" +If the return is from a successful direct invocation, +\fIsigsetjmp\fR() +shall return 0. If the return is from a call to +\fIsiglongjmp\fR(), +\fIsigsetjmp\fR() +shall return a non-zero value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The distinction between +\fIsetjmp\fR()/\c +\fIlongjmp\fR() +and +\fIsigsetjmp\fR()/\c +\fIsiglongjmp\fR() +is only significant for programs which use +\fIsigaction\fR(), +\fIsigprocmask\fR(), +or +\fIsigsuspend\fR(). +.P +Note that since this function is defined in terms of +\fIsetjmp\fR(), +if +.IR savemask +is zero, it is unspecified whether the signal mask is saved. +.SH RATIONALE +The ISO\ C standard specifies various restrictions on the usage of the +\fIsetjmp\fR() +macro in order to permit implementors to recognize the name in the +compiler and not implement an actual function. These same restrictions +apply to the +\fIsigsetjmp\fR() +macro. +.P +There are processors that cannot easily support these calls, but this +was not considered a sufficient reason to exclude them. +.P +4.2 BSD, 4.3 BSD, and XSI-conformant systems provide functions named +\fI_setjmp\fR() +and +\fI_longjmp\fR() +that, together with +\fIsetjmp\fR() +and +\fIlongjmp\fR(), +provide the same functionality as +\fIsigsetjmp\fR() +and +\fIsiglongjmp\fR(). +On those systems, +\fIsetjmp\fR() +and +\fIlongjmp\fR() +save and restore signal masks, while +\fI_setjmp\fR() +and +\fI_longjmp\fR() +do not. On System V Release 3 +and in corresponding issues of the SVID, +\fIsetjmp\fR() +and +\fIlongjmp\fR() +are explicitly defined not to save and restore signal masks. In order +to permit existing practice in both cases, the relation of +\fIsetjmp\fR() +and +\fIlongjmp\fR() +to signal masks is not specified, and a new set of functions is defined +instead. +.P +The +\fIlongjmp\fR() +and +\fIsiglongjmp\fR() +functions operate as in the previous issue provided the matching +\fIsetjmp\fR() +or +\fIsigsetjmp\fR() +has been performed in the same thread. Non-local jumps into contexts +saved by other threads would be at best a questionable practice and +were not considered worthy of standardization. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsiglongjmp\fR\^(\|)", +.IR "\fIsignal\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigsuspend.3p b/upstream/archlinux/man3p/sigsuspend.3p new file mode 100644 index 00000000..5fb28867 --- /dev/null +++ b/upstream/archlinux/man3p/sigsuspend.3p @@ -0,0 +1,130 @@ +'\" et +.TH SIGSUSPEND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigsuspend +\(em wait for a signal +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigsuspend(const sigset_t *\fIsigmask\fP); +.fi +.SH DESCRIPTION +The +\fIsigsuspend\fR() +function shall replace the current signal mask of the calling thread +with the set of signals pointed to by +.IR sigmask +and then suspend the thread until delivery of a signal whose action is +either to execute a signal-catching function or to terminate the +process. This shall not cause any other signals that may have been +pending on the process to become pending on the thread. +.P +If the action is to terminate the process then +\fIsigsuspend\fR() +shall never return. If the action is to execute a signal-catching +function, then +\fIsigsuspend\fR() +shall return after the signal-catching function returns, with the +signal mask restored to the set that existed prior to the +\fIsigsuspend\fR() +call. +.P +It is not possible to block signals that cannot be ignored. This is +enforced by the system without causing an error to be indicated. +.SH "RETURN VALUE" +Since +\fIsigsuspend\fR() +suspends thread execution indefinitely, there is no successful +completion return value. If a return occurs, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIsigsuspend\fR() +function shall fail if: +.TP +.BR EINTR +A signal is caught by the calling process and control is returned from +the signal-catching function. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Normally, at the beginning of a critical code section, a specified set +of signals is blocked using the +\fIsigprocmask\fR() +function. When the thread has completed the critical section and +needs to wait for the previously blocked signal(s), it pauses by +calling +\fIsigsuspend\fR() +with the mask that was returned by the +\fIsigprocmask\fR() +call. +.SH RATIONALE +Code which wants to avoid the ambiguity of the signal mask for thread +cancellation handlers can install an additional cancellation handler +which resets the signal mask to the expected value. +.sp +.RS 4 +.nf + +void cleanup(void *arg) +{ + sigset_t *ss = (sigset_t *) arg; + pthread_sigmask(SIG_SETMASK, ss, NULL); +} +.P +int call_sigsuspend(const sigset_t *mask) +{ + sigset_t oldmask; + int result; + pthread_sigmask(SIG_SETMASK, NULL, &oldmask); + pthread_cleanup_push(cleanup, &oldmask); + result = sigsuspend(sigmask); + pthread_cleanup_pop(0); + return result; +} +.fi +.P +.RE +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "\fIpause\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigaddset\fR\^(\|)", +.IR "\fIsigdelset\fR\^(\|)", +.IR "\fIsigemptyset\fR\^(\|)", +.IR "\fIsigfillset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigtimedwait.3p b/upstream/archlinux/man3p/sigtimedwait.3p new file mode 100644 index 00000000..361ad755 --- /dev/null +++ b/upstream/archlinux/man3p/sigtimedwait.3p @@ -0,0 +1,363 @@ +'\" et +.TH SIGTIMEDWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigtimedwait, +sigwaitinfo +\(em wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigtimedwait(const sigset_t *restrict \fIset\fP, + siginfo_t *restrict \fIinfo\fP, + const struct timespec *restrict \fItimeout\fP); +int sigwaitinfo(const sigset_t *restrict \fIset\fP, + siginfo_t *restrict \fIinfo\fP); +.fi +.SH DESCRIPTION +The +\fIsigtimedwait\fR() +function shall be equivalent to +\fIsigwaitinfo\fR() +except that if none of the signals specified by +.IR set +are pending, +\fIsigtimedwait\fR() +shall wait for the time interval specified in the +.BR timespec +structure referenced by +.IR timeout . +If the +.BR timespec +structure pointed to by +.IR timeout +is zero-valued and if none of the signals specified by +.IR set +are pending, then +\fIsigtimedwait\fR() +shall return immediately with an error. If +.IR timeout +is the null pointer, the behavior is unspecified. +If the Monotonic Clock option is supported, the CLOCK_MONOTONIC clock +shall be used to measure the time interval specified by the +.IR timeout +argument. +.P +The +\fIsigwaitinfo\fR() +function selects the pending signal from the set specified by +.IR set . +Should any of multiple pending signals in the range SIGRTMIN to +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 +.IR set +is pending at the time of the call, the calling thread shall be +suspended until one or more signals in +.IR set +become pending or until it is interrupted by an unblocked, caught +signal. +.P +The +\fIsigwaitinfo\fR() +function shall be equivalent to the +\fIsigwait\fR() +function, except that the return value and the error reporting method +are different (see RETURN VALUE), and that if the +.IR info +argument is non-NULL, the selected signal number shall be stored in the +.IR si_signo +member, and the cause of the signal shall be stored in the +.IR si_code +member. If any value is queued to the selected signal, the first such +queued value shall be dequeued and, if the +.IR info +argument is non-NULL, the value shall be stored in the +.IR si_value +member of +.IR info . +The system resource used to queue the signal shall be released and +returned to the system for other use. If no value is queued, the +content of the +.IR si_value +member is undefined. If no further signals are queued for the selected +signal, the pending indication for that signal shall be reset. +.SH "RETURN VALUE" +Upon successful completion (that is, one of the signals specified by +.IR set +is pending or is generated) +\fIsigwaitinfo\fR() +and +\fIsigtimedwait\fR() +shall return the selected signal number. Otherwise, the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsigtimedwait\fR() +function shall fail if: +.TP +.BR EAGAIN +No signal specified by +.IR set +was generated within the specified timeout period. +.P +The +\fIsigtimedwait\fR() +and +\fIsigwaitinfo\fR() +functions may fail if: +.TP +.BR EINTR +The wait was interrupted by an unblocked, caught signal. It shall be +documented in system documentation whether this error causes these +functions to fail. +.br +.P +The +\fIsigtimedwait\fR() +function may also fail if: +.TP +.BR EINVAL +The +.IR timeout +argument specified a +.IR tv_nsec +value less than zero or greater than or equal to 1\|000 million. +.P +An implementation should only check for this error if no signal is +pending in +.IR set +and it is necessary to wait. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIsigtimedwait\fR() +function times out and returns an +.BR [EAGAIN] +error. Application developers should note that this is inconsistent +with other functions such as +\fIpthread_cond_timedwait\fR() +that return +.BR [ETIMEDOUT] . +.P +Note that in order to ensure that generated signals are queued and signal +values passed to +\fIsigqueue\fR() +are available in +.IR si_value , +applications which use +\fIsigwaitinfo\fR() +or +\fIsigtimedwait\fR() +need to set the SA_SIGINFO flag for each signal in the set (see +.IR "Section 2.4" ", " "Signal Concepts"). +This means setting each signal to be handled by a three-argument +signal-catching function, even if the handler will never be called. +It is not possible (portably) to set a signal handler to SIG_DFL while +setting the SA_SIGINFO flag, because assigning to the +.IR sa_handler +member of +.BR "struct sigaction" +instead of the +.IR sa_sigaction +member would result in undefined behavior, and SIG_DFL need not be +assignment-compatible with +.IR sa_sigaction . +Even if an assignment of SIG_DFL to +.IR sa_sigaction +is accepted by the compiler, the implementation need not treat this value +as special\(emit could just be taken as the address of a signal-catching +function. +.SH RATIONALE +Existing programming practice on realtime systems uses the ability to +pause waiting for a selected set of events and handle the first event +that occurs in-line instead of in a signal-handling function. This +allows applications to be written in an event-directed style similar to +a state machine. This style of programming is useful for largescale +transaction processing in which the overall throughput of an +application and the ability to clearly track states are more important +than the ability to minimize the response time of individual event +handling. +.P +It is possible to construct a signal-waiting macro function out of the +realtime signal function mechanism defined in this volume of POSIX.1\(hy2017. However, such a +macro has to include the definition of a generalized handler for all +signals to be waited on. A significant portion of the overhead of +handler processing can be avoided if the signal-waiting function is +provided by the kernel. This volume of POSIX.1\(hy2017 therefore provides two signal-waiting +functions\(emone that waits indefinitely and one with a timeout\(emas +part of the overall realtime signal function specification. +.P +The specification of a function with a timeout allows an application +to be written that can be broken out of a wait after a set period of +time if no event has occurred. It was argued that setting a timer +event before the wait and recognizing the timer event in the wait would +also implement the same functionality, but at a lower performance +level. Because of the performance degradation associated with the +user-level specification of a timer event and the subsequent +cancellation of that timer event after the wait completes for a valid +event, and the complexity associated with handling potential race +conditions associated with the user-level method, the separate +function has been included. +.P +Note that the semantics of the +\fIsigwaitinfo\fR() +function are nearly identical to that of the +\fIsigwait\fR() +function defined by this volume of POSIX.1\(hy2017. The only difference is that +\fIsigwaitinfo\fR() +returns the queued signal value in the +.IR value +argument. The return of the queued value is required so that +applications can differentiate between multiple events queued to the +same signal number. +.P +The two distinct functions are being maintained because some +implementations may choose to implement the POSIX Threads Extension functions and not +implement the queued signals extensions. Note, though, that +\fIsigwaitinfo\fR() +does not return the queued value if the +.IR value +argument is NULL, so the POSIX Threads Extension +\fIsigwait\fR() +function can be implemented as a macro on +\fIsigwaitinfo\fR(). +.P +The +\fIsigtimedwait\fR() +function was separated from the +\fIsigwaitinfo\fR() +function to address concerns regarding the overloading of the +.IR timeout +pointer to indicate indefinite wait (no timeout), timed wait, and +immediate return, and concerns regarding consistency with other +functions where the conditional and timed waits were separate +functions from the pure blocking function. The semantics of +\fIsigtimedwait\fR() +are specified such that +\fIsigwaitinfo\fR() +could be implemented as a macro with a null pointer for +.IR timeout . +.P +The +.IR sigwait +functions provide a synchronous mechanism for threads to wait for +asynchronously-generated signals. One important question was how many +threads that are suspended in a call to a +\fIsigwait\fR() +function for a signal should return from the call when the signal is +sent. Four choices were considered: +.IP " 1." 4 +Return an error for multiple simultaneous calls to +.IR sigwait +functions for the same signal. +.IP " 2." 4 +One or more threads return. +.IP " 3." 4 +All waiting threads return. +.IP " 4." 4 +Exactly one thread returns. +.P +Prohibiting multiple calls to +\fIsigwait\fR() +for the same signal was felt to be overly restrictive. The ``one or +more'' behavior made implementation of conforming packages easy at the +expense of forcing POSIX threads clients to protect against multiple +simultaneous calls to +\fIsigwait\fR() +in application code in order to achieve predictable behavior. There +was concern that the ``all waiting threads'' behavior would result in +``signal broadcast storms'', consuming excessive CPU resources by +replicating the signals in the general case. Furthermore, no +convincing examples could be presented that delivery to all was either +simpler or more powerful than delivery to one. +.P +Thus, the consensus was that exactly one thread that was suspended in a +call to a +.IR sigwait +function for a signal should return when that signal occurs. This is +not an onerous restriction as: +.IP " *" 4 +A multi-way signal wait can be built from the single-way wait. +.IP " *" 4 +Signals should only be handled by application-level code, as library +routines cannot guess what the application wants to do with signals +generated for the entire process. +.IP " *" 4 +Applications can thus arrange for a single thread to wait for any given +signal and call any needed routines upon its arrival. +.P +In an application that is using signals for interprocess communication, +signal processing is typically done in one place. Alternatively, if +the signal is being caught so that process cleanup can be done, the +signal handler thread can call separate process cleanup routines for +each portion of the application. Since the application main line +started each portion of the application, it is at the right abstraction +level to tell each portion of the application to clean up. +.P +Certainly, there exist programming styles where it is logical to +consider waiting for a single signal in multiple threads. A simple +\fIsigwait_multiple\fR() +routine can be constructed to achieve this goal. A possible +implementation would be to have each +\fIsigwait_multiple\fR() +caller registered as having expressed interest in a set of signals. +The caller then waits on a thread-specific condition variable. A +single server thread calls a +\fIsigwait\fR() +function on the union of all registered signals. When the +\fIsigwait\fR() +function returns, the appropriate state is set and condition variables +are broadcast. New +\fIsigwait_multiple\fR() +callers may cause the pending +\fIsigwait\fR() +call to be canceled and reissued in order to update the set of signals +being waited for. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "Section 2.8.1" ", " "Realtime Signals", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIsigwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigwait.3p b/upstream/archlinux/man3p/sigwait.3p new file mode 100644 index 00000000..11531e87 --- /dev/null +++ b/upstream/archlinux/man3p/sigwait.3p @@ -0,0 +1,147 @@ +'\" et +.TH SIGWAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigwait +\(em wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigwait(const sigset_t *restrict \fIset\fP, int *restrict \fIsig\fP); +.fi +.SH DESCRIPTION +The +\fIsigwait\fR() +function shall select a pending signal from +.IR set , +atomically clear it from the system's set of pending signals, and +return that signal number in the location referenced by +.IR sig . +If prior to the call to +\fIsigwait\fR() +there are multiple pending instances of a single signal number, it is +implementation-defined whether upon successful return there are any +remaining pending signals for that signal number. +If the implementation supports queued signals and there are multiple +signals queued for the signal number selected, the first such queued +signal shall cause a return from +\fIsigwait\fR() +and the remainder shall remain queued. If no signal in +.IR set +is pending at the time of the call, the thread shall be suspended +until one or more becomes pending. The signals defined by +.IR set +shall have been blocked at the time of the call to +\fIsigwait\fR(); +otherwise, the behavior is undefined. The effect of +\fIsigwait\fR() +on the signal actions for the signals in +.IR set +is unspecified. +.P +If more than one thread is using +\fIsigwait\fR() +to wait for the same signal, no more than one of these threads shall +return from +\fIsigwait\fR() +with the signal number. If more than a single thread is blocked in +\fIsigwait\fR() +for a signal when that signal is generated for the process, it is +unspecified which of the waiting threads returns from +\fIsigwait\fR(). +If the signal is generated for a specific thread, as by +\fIpthread_kill\fR(), +only that thread shall return. +.P +Should any of the multiple pending signals in the range SIGRTMIN to +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. +.SH "RETURN VALUE" +Upon successful completion, +\fIsigwait\fR() +shall store the signal number of the received signal at the location +referenced by +.IR sig +and return zero. Otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +The +\fIsigwait\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR set +argument contains an invalid or unsupported signal number. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +To provide a convenient way for a thread to wait for a signal, this volume of POSIX.1\(hy2017 +provides the +\fIsigwait\fR() +function. For most cases where a thread has to wait for a signal, the +\fIsigwait\fR() +function should be quite convenient, efficient, and adequate. +.P +However, requests were made for a lower-level primitive than +\fIsigwait\fR() +and for semaphores that could be used by threads. After some +consideration, threads were allowed to use semaphores and +\fIsem_post\fR() +was defined to be async-signal-safe. +.P +In summary, when it is necessary for code run in response to an +asynchronous signal to notify a thread, +\fIsigwait\fR() +should be used to handle the signal. Alternatively, if the +implementation provides semaphores, they also can be used, either +following +\fIsigwait\fR() +or from within a signal handling routine previously registered with +\fIsigaction\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4" ", " "Signal Concepts", +.IR "Section 2.8.1" ", " "Realtime Signals", +.IR "\fIpause\fR\^(\|)", +.IR "\fIpthread_sigmask\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigpending\fR\^(\|)", +.IR "\fIsigsuspend\fR\^(\|)", +.IR "\fIsigtimedwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sigwaitinfo.3p b/upstream/archlinux/man3p/sigwaitinfo.3p new file mode 100644 index 00000000..473a64eb --- /dev/null +++ b/upstream/archlinux/man3p/sigwaitinfo.3p @@ -0,0 +1,40 @@ +'\" et +.TH SIGWAITINFO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sigwaitinfo +\(em wait for queued signals +.SH SYNOPSIS +.LP +.nf +#include +.P +int sigwaitinfo(const sigset_t *restrict \fIset\fP, siginfo_t *restrict \fIinfo\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsigtimedwait\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sin.3p b/upstream/archlinux/man3p/sin.3p new file mode 100644 index 00000000..598bd81a --- /dev/null +++ b/upstream/archlinux/man3p/sin.3p @@ -0,0 +1,162 @@ +'\" et +.TH SIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sin, +sinf, +sinl +\(em sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +double sin(double \fIx\fP); +float sinf(float \fIx\fP); +long double sinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the sine of their argument +.IR x , +measured in radians. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the sine of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIsin\fR(), +\fIsinf\fR(), +and +\fIsinl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The +.IR x +argument is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Sine of a 45-Degree Angle" +.sp +.RS 4 +.nf + +#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = sin(radians); +.fi +.P +.RE +.SH "APPLICATION USAGE" +These functions may lose accuracy when their argument is near a +multiple of \(*p or is far from 0.0. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasin\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sinh.3p b/upstream/archlinux/man3p/sinh.3p new file mode 100644 index 00000000..c218c293 --- /dev/null +++ b/upstream/archlinux/man3p/sinh.3p @@ -0,0 +1,147 @@ +'\" et +.TH SINH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sinh, +sinhf, +sinhl +\(em hyperbolic sine functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double sinh(double \fIx\fP); +float sinhf(float \fIx\fP); +long double sinhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the hyperbolic sine of their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the hyperbolic +sine of +.IR x . +.P +If the result would cause an overflow, a range error shall occur and +\(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL (with the same sign as +.IR x ) +shall be returned as appropriate for the type of the function. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fIsinh\fR(), +\fIsinhf\fR(), +and +\fIsinhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions shall fail if: +.IP "Range\ Error" 12 +The result would cause an overflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Range\ Error" 12 +The value +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasinh\fR\^(\|)", +.IR "\fIcosh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fItanh\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sinl.3p b/upstream/archlinux/man3p/sinl.3p new file mode 100644 index 00000000..b702a984 --- /dev/null +++ b/upstream/archlinux/man3p/sinl.3p @@ -0,0 +1,40 @@ +'\" et +.TH SINL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sinl +\(em sine function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double sinl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIsin\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sleep.3p b/upstream/archlinux/man3p/sleep.3p new file mode 100644 index 00000000..26b5b3ed --- /dev/null +++ b/upstream/archlinux/man3p/sleep.3p @@ -0,0 +1,237 @@ +'\" et +.TH SLEEP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sleep +\(em suspend execution for an interval of time +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned sleep(unsigned \fIseconds\fP); +.fi +.SH DESCRIPTION +The +\fIsleep\fR() +function shall cause the calling thread to be suspended from execution +until either the number of realtime seconds specified by the argument +.IR seconds +has elapsed or a signal is delivered to the calling thread and its +action is to invoke a signal-catching function or to terminate the +process. The suspension time may be longer than requested due to the +scheduling of other activity by the system. +.P +In single-threaded programs, +\fIsleep\fR() +may make use of SIGALRM. In multi-threaded programs, +\fIsleep\fR() +shall not make use of SIGALRM and the remainder of this DESCRIPTION +does not apply. +.P +If a SIGALRM signal is generated for the calling process during +execution of +\fIsleep\fR() +and if the SIGALRM signal is being ignored or blocked from delivery, it +is unspecified whether +\fIsleep\fR() +returns when the SIGALRM signal is scheduled. If the signal is being +blocked, it is also unspecified whether it remains pending after +\fIsleep\fR() +returns or it is discarded. +.P +If a SIGALRM signal is generated for the calling process during +execution of +\fIsleep\fR(), +except as a result of a prior call to +\fIalarm\fR(), +and if the SIGALRM signal is not being ignored or blocked from +delivery, it is unspecified whether that signal has any effect other +than causing +\fIsleep\fR() +to return. +.P +If a signal-catching function interrupts +\fIsleep\fR() +and examines or changes either the time a SIGALRM is scheduled to be +generated, the action associated with the SIGALRM signal, or whether +the SIGALRM signal is blocked from delivery, the results are +unspecified. +.P +If a signal-catching function interrupts +\fIsleep\fR() +and calls +\fIsiglongjmp\fR() +or +\fIlongjmp\fR() +to restore an environment saved prior to the +\fIsleep\fR() +call, the action associated with the SIGALRM signal and the time at +which a SIGALRM signal is scheduled to be generated are unspecified. +It is also unspecified whether the SIGALRM signal is blocked, unless +the signal mask of the process is restored as part of the environment. +.P +Interactions between +\fIsleep\fR() +and +\fIsetitimer\fR() +are unspecified. +.SH "RETURN VALUE" +If +\fIsleep\fR() +returns because the requested time has elapsed, the value returned +shall be 0. If +\fIsleep\fR() +returns due to delivery of a signal, the return value shall be +the ``unslept'' amount (the requested time minus the time actually +slept) in seconds. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +There are two general approaches to the implementation of the +\fIsleep\fR() +function. One is to use the +\fIalarm\fR() +function to schedule a SIGALRM +signal and then suspend the calling thread waiting for that signal. The +other is to implement an independent facility. This volume of POSIX.1\(hy2017 permits either +approach in single-threaded programs, but the simple alarm/suspend +implementation is not appropriate for multi-threaded programs. +.P +In order to comply with the requirement that no primitive shall change +a process attribute unless explicitly described by this volume of POSIX.1\(hy2017, an +implementation using SIGALRM must carefully take into account any +SIGALRM signal scheduled by previous +\fIalarm\fR() +calls, the action previously established for SIGALRM, and whether +SIGALRM was blocked. If a SIGALRM has been scheduled before the +\fIsleep\fR() +would ordinarily complete, the +\fIsleep\fR() +must be shortened to that time and a SIGALRM generated (possibly +simulated by direct invocation of the signal-catching function) before +\fIsleep\fR() +returns. If a SIGALRM has been scheduled after the +\fIsleep\fR() +would ordinarily complete, it must be rescheduled for the same time +before +\fIsleep\fR() +returns. The action and blocking for SIGALRM must be saved and +restored. +.P +Historical implementations often implement the SIGALRM-based version +using +\fIalarm\fR() +and +\fIpause\fR(). +One such implementation is prone to infinite hangups, as described in +.IR "\fIpause\fR\^(\|)". +Another such implementation uses the C-language +\fIsetjmp\fR() +and +\fIlongjmp\fR() +functions to avoid that window. That implementation introduces a +different problem: when the SIGALRM signal interrupts a signal-catching +function installed by the user to catch a different signal, the +\fIlongjmp\fR() +aborts that signal-catching function. An implementation based on +\fIsigprocmask\fR(), +\fIalarm\fR(), +and +\fIsigsuspend\fR() +can avoid these problems. +.P +Despite all reasonable care, there are several very subtle, but +detectable and unavoidable, differences between the two types of +implementations. These are the cases mentioned in this volume of POSIX.1\(hy2017 where +some other activity relating to SIGALRM takes place, and the results +are stated to be unspecified. All of these cases are sufficiently +unusual as not to be of concern to most applications. +.P +See also the discussion of the term +.IR realtime +in +.IR "\fIalarm\fR\^(\|)". +.P +Since +\fIsleep\fR() +can be implemented using +\fIalarm\fR(), +the discussion about alarms occurring early under +\fIalarm\fR() +applies to +\fIsleep\fR() +as well. +.P +Application developers should note that the type of the argument +.IR seconds +and the return value of +\fIsleep\fR() +is +.BR unsigned . +That means that a Strictly Conforming POSIX System Interfaces +Application +cannot pass a value greater than the minimum guaranteed value for +{UINT_MAX}, +which the ISO\ C standard sets as 65\|535, and any application passing a larger +value is restricting its portability. A different type was considered, +but historical implementations, including those with a 16-bit +.BR int +type, consistently use either +.BR unsigned +or +.BR int . +.P +Scheduling delays may cause the process to return from the +\fIsleep\fR() +function significantly after the requested time. In such cases, the +return value should be set to zero, since the formula (requested time +minus the time actually spent) yields a negative number and +\fIsleep\fR() +returns an +.BR unsigned . +.SH "FUTURE DIRECTIONS" +A future version of this standard may require that +\fIsleep\fR() +does not make use of SIGALRM in all programs, not just multi-threaded +programs. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIgetitimer\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpause\fR\^(\|)", +.IR "\fIsigaction\fR\^(\|)", +.IR "\fIsigsetjmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/snprintf.3p b/upstream/archlinux/man3p/snprintf.3p new file mode 100644 index 00000000..281d3bd3 --- /dev/null +++ b/upstream/archlinux/man3p/snprintf.3p @@ -0,0 +1,41 @@ +'\" et +.TH SNPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +snprintf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int snprintf(char *restrict \fIs\fP, size_t \fIn\fP, + const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sockatmark.3p b/upstream/archlinux/man3p/sockatmark.3p new file mode 100644 index 00000000..0e3451db --- /dev/null +++ b/upstream/archlinux/man3p/sockatmark.3p @@ -0,0 +1,151 @@ +'\" et +.TH SOCKATMARK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sockatmark +\(em determine whether a socket is at the out-of-band mark +.SH SYNOPSIS +.LP +.nf +#include +.P +int sockatmark(int \fIs\fR); +.fi +.SH DESCRIPTION +The +\fIsockatmark\fR() +function shall determine whether the socket specified by the descriptor +.IR s +is at the out-of-band data mark (see +.IR "Section 2.10.12" ", " "Socket Out-of-Band Data State"). +If the protocol for the socket supports out-of-band data by marking the +stream with an out-of-band data mark, the +\fIsockatmark\fR() +function shall return 1 when all data preceding the mark has been read +and the out-of-band data mark is the first element in the receive +queue. The +\fIsockatmark\fR() +function shall not remove the mark from the stream. +.SH "RETURN VALUE" +Upon successful completion, the +\fIsockatmark\fR() +function shall return a value indicating whether the socket is at an +out-of-band data mark. If the protocol has marked the data stream and +all data preceding the mark has been read, the return value shall be 1; +if there is no mark, or if data precedes the mark in the receive queue, +the +\fIsockatmark\fR() +function shall return 0. Otherwise, it shall return a value of \-1 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsockatmark\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR s +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR s +argument is not a socket. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The use of this function between receive operations allows an +application to determine which received data precedes the out-of-band +data and which follows the out-of-band data. +.P +There is an inherent race condition in the use of this function. On an +empty receive queue, the current read of the location might well be at +the ``mark'', but the system has no way of knowing that the next data +segment that will arrive from the network will carry the mark, and +\fIsockatmark\fR() +will return false, and the next read operation will silently consume +the mark. +.P +Hence, this function can only be used reliably when the application +already knows that the out-of-band data has been seen by the system or +that it is known that there is data waiting to be read at the socket +(via SIGURG or +\fIselect\fR()). +See +.IR "Section 2.10.11" ", " "Socket Receive Queue", +.IR "Section 2.10.12" ", " "Socket Out-of-Band Data State", +.IR "Section 2.10.14" ", " "Signals", +and +\fIpselect\fR() +for details. +.SH RATIONALE +The +\fIsockatmark\fR() +function replaces the historical SIOCATMARK command to +\fIioctl\fR() +which implemented the same functionality on many implementations. Using +a wrapper function follows the adopted conventions to avoid specifying +commands to the +\fIioctl\fR() +function, other than those now included to support XSI STREAMS. The +\fIsockatmark\fR() +function could be implemented as follows: +.sp +.RS 4 +.nf + +#include +.P +int sockatmark(int s) +{ + int val; + if (ioctl(s,SIOCATMARK,&val)==-1) + return(-1); + return(val); +} +.fi +.P +.RE +.P +The use of +.BR [ENOTTY] +to indicate an incorrect descriptor type matches the historical +behavior of SIOCATMARK. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.10.12" ", " "Socket Out-of-Band Data State", +.IR "\fIpselect\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/socket.3p b/upstream/archlinux/man3p/socket.3p new file mode 100644 index 00000000..65f3ff7c --- /dev/null +++ b/upstream/archlinux/man3p/socket.3p @@ -0,0 +1,186 @@ +'\" et +.TH SOCKET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +socket +\(em create an endpoint for communication +.SH SYNOPSIS +.LP +.nf +#include +.P +int socket(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP); +.fi +.SH DESCRIPTION +The +\fIsocket\fR() +function shall create an unbound socket in a communications domain, and +return a file descriptor that can be used in later function calls that +operate on sockets. The file descriptor shall be allocated as described in +.IR "Section 2.14" ", " "File Descriptor Allocation". +.P +The +\fIsocket\fR() +function takes the following arguments: +.IP "\fIdomain\fR" 12 +Specifies the communications domain in which a socket is to be +created. +.IP "\fItype\fR" 12 +Specifies the type of socket to be created. +.IP "\fIprotocol\fR" 12 +Specifies a particular protocol to be used with the socket. Specifying +a +.IR protocol +of 0 causes +\fIsocket\fR() +to use an unspecified default protocol appropriate for the requested +socket type. +.P +The +.IR domain +argument specifies the address family used in the communications +domain. The address families supported by the system are +implementation-defined. +.P +Symbolic constants that can be used for the domain argument are defined +in the +.IR +header. +.P +The +.IR type +argument specifies the socket type, which determines the semantics of +communication over the socket. The following socket types are defined; +implementations may specify additional socket types: +.IP SOCK_STREAM 12 +Provides sequenced, reliable, bidirectional, connection-mode byte +streams, and may provide a transmission mechanism for out-of-band +data. +.IP SOCK_DGRAM 12 +Provides datagrams, which are connectionless-mode, unreliable messages +of fixed maximum length. +.IP SOCK_SEQPACKET 12 +.br +Provides sequenced, reliable, bidirectional, connection-mode +transmission paths for records. A record can be sent using one or more +output operations and received using one or more input operations, but +a single operation never transfers part of more than one record. Record +boundaries are visible to the receiver via the MSG_EOR flag. +.P +If the +.IR protocol +argument is non-zero, it shall specify a protocol that is supported by +the address family. If the +.IR protocol +argument is zero, the default protocol for this address family and type +shall be used. The protocols supported by the system are +implementation-defined. +.P +The process may need to have appropriate privileges to use the +\fIsocket\fR() +function or to create some sockets. +.SH "RETURN VALUE" +Upon successful completion, +\fIsocket\fR() +shall return a non-negative integer, the socket file descriptor. +Otherwise, a value of \-1 shall be returned and +.IR errno +set to indicate the error. +.br +.SH ERRORS +The +\fIsocket\fR() +function shall fail if: +.TP +.BR EAFNOSUPPORT +.br +The implementation does not support the specified address family. +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR ENFILE +No more file descriptors are available for the system. +.TP +.BR EPROTONOSUPPORT +.br +The protocol is not supported by the address family, or the protocol is +not supported by the implementation. +.TP +.BR EPROTOTYPE +The socket type is not supported by the protocol. +.P +The +\fIsocket\fR() +function may fail if: +.TP +.BR EACCES +The process does not have appropriate privileges. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The documentation for specific address families specifies which +protocols each address family supports. The documentation for specific +protocols specifies which socket types each protocol supports. +.P +The application can determine whether an address family is supported by +trying to create a socket with +.IR domain +set to the protocol in question. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "File Descriptor Allocation", +.IR "\fIaccept\fR\^(\|)", +.IR "\fIbind\fR\^(\|)", +.IR "\fIconnect\fR\^(\|)", +.IR "\fIgetsockname\fR\^(\|)", +.IR "\fIgetsockopt\fR\^(\|)", +.IR "\fIlisten\fR\^(\|)", +.IR "\fIrecv\fR\^(\|)", +.IR "\fIrecvfrom\fR\^(\|)", +.IR "\fIrecvmsg\fR\^(\|)", +.IR "\fIsend\fR\^(\|)", +.IR "\fIsendmsg\fR\^(\|)", +.IR "\fIsetsockopt\fR\^(\|)", +.IR "\fIshutdown\fR\^(\|)", +.IR "\fIsocketpair\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/socketpair.3p b/upstream/archlinux/man3p/socketpair.3p new file mode 100644 index 00000000..c3bf3e2f --- /dev/null +++ b/upstream/archlinux/man3p/socketpair.3p @@ -0,0 +1,178 @@ +'\" et +.TH SOCKETPAIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +socketpair +\(em create a pair of connected sockets +.SH SYNOPSIS +.LP +.nf +#include +.P +int socketpair(int \fIdomain\fP, int \fItype\fP, int \fIprotocol\fP, + int \fIsocket_vector\fP[2]); +.fi +.SH DESCRIPTION +The +\fIsocketpair\fR() +function shall create an unbound pair of connected sockets in a +specified +.IR domain , +of a specified +.IR type , +under the protocol optionally specified by the +.IR protocol +argument. The two sockets shall be identical. The file descriptors +used in referencing the created sockets shall be returned in +.IR socket_vector [0] +and +.IR socket_vector [1]. +The file descriptors shall be allocated as described in +.IR "Section 2.14" ", " "File Descriptor Allocation". +.P +The +\fIsocketpair\fR() +function takes the following arguments: +.IP "\fIdomain\fR" 12 +Specifies the communications domain in which the sockets are to be +created. +.IP "\fItype\fR" 12 +Specifies the type of sockets to be created. +.IP "\fIprotocol\fR" 12 +Specifies a particular protocol to be used with the sockets. +Specifying a +.IR protocol +of 0 causes +\fIsocketpair\fR() +to use an unspecified default protocol appropriate for the requested +socket type. +.IP "\fIsocket_vector\fR" 12 +Specifies a 2-integer array to hold the file descriptors of the created +socket pair. +.P +The +.IR type +argument specifies the socket type, which determines the semantics of +communications over the socket. The following socket types are defined; +implementations may specify additional socket types: +.IP SOCK_STREAM 14 +Provides sequenced, reliable, bidirectional, connection-mode byte +streams, and may provide a transmission mechanism for out-of-band +data. +.IP SOCK_DGRAM 14 +Provides datagrams, which are connectionless-mode, unreliable messages +of fixed maximum length. +.IP SOCK_SEQPACKET 14 +Provides sequenced, reliable, bidirectional, connection-mode +transmission paths for records. A record can be sent using one or more +output operations and received using one or more input operations, but +a single operation never transfers part of more than one record. Record +boundaries are visible to the receiver via the MSG_EOR flag. +.P +If the +.IR protocol +argument is non-zero, it shall specify a protocol that is supported by +the address family. If the +.IR protocol +argument is zero, the default protocol for this address family and type +shall be used. The protocols supported by the system are +implementation-defined. +.P +The process may need to have appropriate privileges to use the +\fIsocketpair\fR() +function or to create some sockets. +.SH "RETURN VALUE" +Upon successful completion, this function shall return 0; otherwise, +\-1 shall be returned and +.IR errno +set to indicate the error, no file descriptors shall be allocated, +and the contents of +.IR socket_vector +shall be left unmodified. +.SH ERRORS +The +\fIsocketpair\fR() +function shall fail if: +.TP +.BR EAFNOSUPPORT +.br +The implementation does not support the specified address family. +.TP +.BR EMFILE +All, or all but one, of the file descriptors available to the +process are currently open. +.TP +.BR ENFILE +No more file descriptors are available for the system. +.TP +.BR EOPNOTSUPP +The specified protocol does not permit creation of socket pairs. +.TP +.BR EPROTONOSUPPORT +.br +The protocol is not supported by the address family, or the protocol is +not supported by the implementation. +.TP +.BR EPROTOTYPE +The socket type is not supported by the protocol. +.P +The +\fIsocketpair\fR() +function may fail if: +.TP +.BR EACCES +The process does not have appropriate privileges. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENOMEM +Insufficient memory was available to fulfill the request. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +None. +.SH "APPLICATION USAGE" +The documentation for specific address families specifies which +protocols each address family supports. The documentation for specific +protocols specifies which socket types each protocol supports. +.P +The +\fIsocketpair\fR() +function is used primarily with UNIX domain sockets and need not be +supported for other domains. +.SH "RATIONALE" +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "File Descriptor Allocation", +.IR "\fIsocket\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sprintf.3p b/upstream/archlinux/man3p/sprintf.3p new file mode 100644 index 00000000..8462bdb1 --- /dev/null +++ b/upstream/archlinux/man3p/sprintf.3p @@ -0,0 +1,40 @@ +'\" et +.TH SPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sprintf +\(em print formatted output +.SH SYNOPSIS +.LP +.nf +#include +.P +int sprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sqrt.3p b/upstream/archlinux/man3p/sqrt.3p new file mode 100644 index 00000000..0fbd24a2 --- /dev/null +++ b/upstream/archlinux/man3p/sqrt.3p @@ -0,0 +1,138 @@ +'\" et +.TH SQRT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.EQ +delim $$ +.EN +.SH NAME +sqrt, +sqrtf, +sqrtl +\(em square root function +.SH SYNOPSIS +.LP +.nf +#include +.P +double sqrt(double \fIx\fP); +float sqrtf(float \fIx\fP); +long double sqrtl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the square root of their argument +.IR x , +$sqrt {x}$. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the square +root of +.IR x . +.P +For finite values of +.IR x +< \-0, a domain error shall occur, and +either a NaN (if supported), or +an implementation-defined value shall be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or +Inf, +.IR x +shall be returned. +.P +If +.IR x +is \-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The finite value of +.IR x +is < \-0, +or +.IR x +is \-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Square Root of 9.0" +.sp +.RS 4 +.nf + +#include +\&... +double x = 9.0; +double result; +\&... +result = sqrt(x); +.fi +.P +.RE +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/srand.3p b/upstream/archlinux/man3p/srand.3p new file mode 100644 index 00000000..2df23c13 --- /dev/null +++ b/upstream/archlinux/man3p/srand.3p @@ -0,0 +1,40 @@ +'\" et +.TH SRAND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +srand +\(em pseudo-random number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void srand(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIrand\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/srand48.3p b/upstream/archlinux/man3p/srand48.3p new file mode 100644 index 00000000..c7a45edb --- /dev/null +++ b/upstream/archlinux/man3p/srand48.3p @@ -0,0 +1,41 @@ +'\" et +.TH SRAND48 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +srand48 +\(em seed the uniformly distributed double-precision pseudo-random +number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void srand48(long \fIseedval\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIdrand48\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/srandom.3p b/upstream/archlinux/man3p/srandom.3p new file mode 100644 index 00000000..3cda426e --- /dev/null +++ b/upstream/archlinux/man3p/srandom.3p @@ -0,0 +1,40 @@ +'\" et +.TH SRANDOM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +srandom +\(em seed pseudo-random number generator +.SH SYNOPSIS +.LP +.nf +#include +.P +void srandom(unsigned \fIseed\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIinitstate\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sscanf.3p b/upstream/archlinux/man3p/sscanf.3p new file mode 100644 index 00000000..dd77ff4f --- /dev/null +++ b/upstream/archlinux/man3p/sscanf.3p @@ -0,0 +1,40 @@ +'\" et +.TH SSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sscanf +\(em convert formatted input +.SH SYNOPSIS +.LP +.nf +#include +.P +int sscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/stat.3p b/upstream/archlinux/man3p/stat.3p new file mode 100644 index 00000000..018ac97a --- /dev/null +++ b/upstream/archlinux/man3p/stat.3p @@ -0,0 +1,40 @@ +'\" et +.TH STAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +stat +\(em get file status +.SH SYNOPSIS +.LP +.nf +#include +.P +int stat(const char *restrict \fIpath\fP, struct stat *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfstatat\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/statvfs.3p b/upstream/archlinux/man3p/statvfs.3p new file mode 100644 index 00000000..ff18299b --- /dev/null +++ b/upstream/archlinux/man3p/statvfs.3p @@ -0,0 +1,40 @@ +'\" et +.TH STATVFS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +statvfs +\(em get file system information +.SH SYNOPSIS +.LP +.nf +#include +.P +int statvfs(const char *restrict \fIpath\fP, struct statvfs *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfstatvfs\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/stdin.3p b/upstream/archlinux/man3p/stdin.3p new file mode 100644 index 00000000..4e09ed9b --- /dev/null +++ b/upstream/archlinux/man3p/stdin.3p @@ -0,0 +1,131 @@ +'\" et +.TH STDIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +stderr, +stdin, +stdout +\(em standard I/O streams +.SH SYNOPSIS +.LP +.nf +#include +.P +extern FILE *stderr, *stdin, *stdout; +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +A file with associated buffering is called a +.IR stream +and is declared to be a pointer to a defined type +.BR FILE . +The +\fIfopen\fR() +function shall create certain descriptive data for a stream and return +a pointer to designate the stream in all further transactions. Normally, +there are three open streams with constant pointers declared in the +.IR +header and associated with the standard open files. +.P +At program start-up, three streams shall be predefined and need not +be opened explicitly: +.IR "standard input" +(for reading conventional input), +.IR "standard output" +(for writing conventional output), and +.IR "standard error" +(for writing diagnostic output). When opened, the standard error +stream is not fully buffered; the standard input and standard output +streams are fully buffered if and only if the stream can be determined +not to refer to an interactive device. +.P +The following symbolic values in +.IR +define the file descriptors that shall be associated with the C-language +.IR stdin , +.IR stdout , +and +.IR stderr +when the application is started: +.IP STDIN_FILENO 14 +Standard input value, +.IR stdin . +Its value is 0. +.IP STDOUT_FILENO 14 +Standard output value, +.IR stdout . +Its value is 1. +.IP STDERR_FILENO 14 +Standard error value, +.IR stderr . +Its value is 2. +.P +The +.IR stderr +stream is expected to be open for reading and writing. +.SH "RETURN VALUE" +None. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfclose\fR\^(\|)", +.IR "\fIfeof\fR\^(\|)", +.IR "\fIferror\fR\^(\|)", +.IR "\fIfileno\fR\^(\|)", +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfread\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIgets\fR\^(\|)", +.IR "\fIpopen\fR\^(\|)", +.IR "\fIputc\fR\^(\|)", +.IR "\fIputs\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)", +.IR "\fIsetvbuf\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fIungetc\fR\^(\|)", +.IR "\fIvfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/stpcpy.3p b/upstream/archlinux/man3p/stpcpy.3p new file mode 100644 index 00000000..a5e930fc --- /dev/null +++ b/upstream/archlinux/man3p/stpcpy.3p @@ -0,0 +1,40 @@ +'\" et +.TH STPCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +stpcpy +\(em copy a string and return a pointer to the end of the result +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpcpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrcpy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/stpncpy.3p b/upstream/archlinux/man3p/stpncpy.3p new file mode 100644 index 00000000..09088f36 --- /dev/null +++ b/upstream/archlinux/man3p/stpncpy.3p @@ -0,0 +1,40 @@ +'\" et +.TH STPNCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +stpncpy +\(em copy fixed length string, returning a pointer to the array end +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpncpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrncpy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strcasecmp.3p b/upstream/archlinux/man3p/strcasecmp.3p new file mode 100644 index 00000000..21da9d57 --- /dev/null +++ b/upstream/archlinux/man3p/strcasecmp.3p @@ -0,0 +1,137 @@ +'\" et +.TH STRCASECMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strcasecmp, +strcasecmp_l, +strncasecmp, +strncasecmp_l +\(em case-insensitive string comparisons +.SH SYNOPSIS +.LP +.nf +#include +.P +int strcasecmp(const char *\fIs1\fP, const char *\fIs2\fP); +int strcasecmp_l(const char *\fIs1\fP, const char *\fIs2\fP, + locale_t \fIlocale\fP); +int strncasecmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP); +int strncasecmp_l(const char *\fIs1\fP, const char *\fIs2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +The +\fIstrcasecmp\fR() +and +\fIstrcasecmp_l\fR() +functions shall compare, while ignoring differences in case, the +string pointed to by +.IR s1 +to the string pointed to by +.IR s2 . +The +\fIstrncasecmp\fR() +and +\fIstrncasecmp_l\fR() +functions shall compare, while ignoring differences in case, not more +than +.IR n +bytes from the string pointed to by +.IR s1 +to the string pointed to by +.IR s2 . +.P +The +\fIstrcasecmp\fR() +and +\fIstrncasecmp\fR() +functions use the current locale to determine the case of the characters. +.P +The +\fIstrcasecmp_l\fR() +and +\fIstrncasecmp_l\fR() +functions use the locale represented by +.IR locale +to determine the case of the characters. +.P +When the +.IR LC_CTYPE +category of the locale being used is from the POSIX locale, these +functions shall behave as if the strings had been converted to lowercase +and then a byte comparison performed. Otherwise, the results are +unspecified. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrcasecmp_l\fR() +or +\fIstrncasecmp_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon completion, +\fIstrcasecmp\fR() +and +\fIstrcasecmp_l\fR() +shall return an integer greater than, equal to, or less than 0, if the +string pointed to by +.IR s1 +is, ignoring case, greater than, equal to, or less than the string +pointed to by +.IR s2 , +respectively. +.P +Upon successful completion, +\fIstrncasecmp\fR() +and +\fIstrncasecmp_l\fR() +shall return an integer greater than, equal to, or less than 0, if the +possibly null-terminated array pointed to by +.IR s1 +is, ignoring case, greater than, equal to, or less than the possibly +null-terminated array pointed to by +.IR s2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscasecmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strcat.3p b/upstream/archlinux/man3p/strcat.3p new file mode 100644 index 00000000..979a84ba --- /dev/null +++ b/upstream/archlinux/man3p/strcat.3p @@ -0,0 +1,80 @@ +'\" et +.TH STRCAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strcat +\(em concatenate two strings +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strcat(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrcat\fR() +function shall append a copy of the string pointed to by +.IR s2 +(including the terminating NUL character) to the end of the string pointed +to by +.IR s1 . +The initial byte of +.IR s2 +overwrites the NUL character at the end of +.IR s1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIstrcat\fR() +function shall return +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This version is aligned with the ISO\ C standard; this does not affect +compatibility with XPG3 applications. Reliable error detection by this +function was never guaranteed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strchr.3p b/upstream/archlinux/man3p/strchr.3p new file mode 100644 index 00000000..ae89da16 --- /dev/null +++ b/upstream/archlinux/man3p/strchr.3p @@ -0,0 +1,73 @@ +'\" et +.TH STRCHR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strchr +\(em string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strchr(const char *\fIs\fP, int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrchr\fR() +function shall locate the first occurrence of +.IR c +(converted to a +.BR char ) +in the string pointed to by +.IR s . +The terminating NUL character is considered to be part of the string. +.SH "RETURN VALUE" +Upon completion, +\fIstrchr\fR() +shall return a pointer to the byte, or a null pointer if the byte +was not found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strcmp.3p b/upstream/archlinux/man3p/strcmp.3p new file mode 100644 index 00000000..d801d722 --- /dev/null +++ b/upstream/archlinux/man3p/strcmp.3p @@ -0,0 +1,127 @@ +'\" et +.TH STRCMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strcmp +\(em compare two strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int strcmp(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrcmp\fR() +function shall compare the string pointed to by +.IR s1 +to the string pointed to by +.IR s2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of bytes (both +interpreted as type +.BR "unsigned char" ) +that differ in the strings being compared. +.SH "RETURN VALUE" +Upon completion, +\fIstrcmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +string pointed to by +.IR s1 +is greater than, equal to, or less than the string pointed to by +.IR s2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Checking a Password Entry" +.P +The following example compares the information read from standard input +to the value of the name of the user entry. If the +\fIstrcmp\fR() +function returns 0 (indicating a match), a further check will be made +to see if the user entered the proper old password. The +\fIcrypt\fR() +function shall encrypt the old password entered by the user, using +the value of the encrypted password in the +.BR passwd +structure as the salt. If this value matches the value of the encrypted +.BR passwd +in the structure, the entered password +.IR oldpasswd +is the correct user's password. Finally, the program encrypts the new +password so that it can store the information in the +.BR passwd +structure. +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +int valid_change; +struct passwd *p; +char user[100]; +char oldpasswd[100]; +char newpasswd[100]; +char savepasswd[100]; +\&... +if (strcmp(p->pw_name, user) == 0) { + if (strcmp(p->pw_passwd, crypt(oldpasswd, p->pw_passwd)) == 0) { + strcpy(savepasswd, crypt(newpasswd, user)); + p->pw_passwd = savepasswd; + valid_change = 1; + } + else { + fprintf(stderr, "Old password is not valid\en"); + } +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strcoll.3p b/upstream/archlinux/man3p/strcoll.3p new file mode 100644 index 00000000..3d2a1f22 --- /dev/null +++ b/upstream/archlinux/man3p/strcoll.3p @@ -0,0 +1,172 @@ +'\" et +.TH STRCOLL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strcoll, +strcoll_l +\(em string comparison using collating information +.SH SYNOPSIS +.LP +.nf +#include +.P +int strcoll(const char *\fIs1\fP, const char *\fIs2\fP); +int strcoll_l(const char *\fIs1\fP, const char *\fIs2\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIstrcoll\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrcoll\fR() +and +\fIstrcoll_l\fR() +functions shall compare the string pointed to by +.IR s1 +to the string pointed to by +.IR s2 , +both interpreted as appropriate to the +.IR LC_COLLATE +category of the current locale, +or of the locale represented by +.IR locale , +respectively. +.P +The +\fIstrcoll\fR() +and +\fIstrcoll_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrcoll\fR(), +or +\fIstrcoll_l\fR() +then check +.IR errno . +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrcoll_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrcoll\fR() +shall return an integer greater than, equal to, or less than +0, according to whether the string pointed to by +.IR s1 +is greater than, equal to, or less than the string pointed to by +.IR s2 +when both are interpreted as appropriate to the current locale. +On error, +\fIstrcoll\fR() +may set +.IR errno , +but no return value is reserved to indicate an error. +.P +Upon successful completion, +\fIstrcoll_l\fR() +shall return an integer greater than, equal to, or less than 0, +according to whether the string pointed to by +.IR s1 +is greater than, equal to, or less than the string pointed to by +.IR s2 +when both are interpreted as appropriate to the locale represented by +.IR locale . +On error, +\fIstrcoll_l\fR() +may set +.IR errno , +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The +.IR s1 +or +.IR s2 +arguments contain characters outside the domain of the collating +sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Comparing Nodes" +.P +The following example uses an application-defined function, +\fInode_compare\fR(), +to compare two nodes based on an alphabetical ordering of the +.IR string +field. +.sp +.RS 4 +.nf + +#include +\&... +struct node { /* These are stored in the table. */ + char *string; + int length; +}; +\&... +int node_compare(const void *node1, const void *node2) +{ + return strcoll(((const struct node *)node1)->string, + ((const struct node *)node2)->string); +} +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +\fIstrxfrm\fR() +and +\fIstrcmp\fR() +functions should be used for sorting large lists. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalphasort\fR\^(\|)", +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrxfrm\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strcpy.3p b/upstream/archlinux/man3p/strcpy.3p new file mode 100644 index 00000000..ff79e367 --- /dev/null +++ b/upstream/archlinux/man3p/strcpy.3p @@ -0,0 +1,180 @@ +'\" et +.TH STRCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +stpcpy, strcpy +\(em copy a string and return a pointer to the end of the result +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpcpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +char *strcpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP); +.fi +.SH DESCRIPTION +For +\fIstrcpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstpcpy\fR() +and +\fIstrcpy\fR() +functions shall copy the string pointed to by +.IR s2 +(including the terminating NUL character) into the array pointed to by +.IR s1 . +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIstpcpy\fR() +function shall return a pointer to the terminating NUL character copied +into the +.IR s1 +buffer. +.P +The +\fIstrcpy\fR() +function shall return +.IR s1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Construction of a Multi-Part Message in a Single Buffer" +.sp +.RS 4 +.nf + +#include +#include +.P +int +main (void) +{ + char buffer [10]; + char *name = buffer; +.P + name = stpcpy (stpcpy (stpcpy (name, "ice"),"-"), "cream"); + puts (buffer); + return 0; +} +.fi +.P +.RE +.SS "Initializing a String" +.P +The following example copies the string +.BR \(dq----------\(dq +into the +.IR permstring +variable. +.sp +.RS 4 +.nf + +#include +\&... +static char permstring[11]; +\&... +strcpy(permstring, "----------"); +\&... +.fi +.P +.RE +.SS "Storing a Key and Data" +.P +The following example allocates space for a key using +\fImalloc\fR() +then uses +\fIstrcpy\fR() +to place the key there. Then it allocates space for data using +\fImalloc\fR(), +and uses +\fIstrcpy\fR() +to place data there. (The user-defined function +\fIdbfree\fR() +frees memory previously allocated to an array of type +.BR "struct element *" .) +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +/* Structure used to read data and store it. */ +struct element { + char *key; + char *data; +}; +.P +struct element *tbl, *curtbl; +char *key, *data; +int count; +\&... +void dbfree(struct element *, int); +\&... +if ((curtbl->key = malloc(strlen(key) + 1)) == NULL) { + perror("malloc"); dbfree(tbl, count); return NULL; +} +strcpy(curtbl->key, key); +.P +if ((curtbl->data = malloc(strlen(data) + 1)) == NULL) { + perror("malloc"); free(curtbl->key); dbfree(tbl, count); return NULL; +} +strcpy(curtbl->data, data); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Character movement is performed differently in different +implementations. Thus, overlapping moves may yield surprises. +.P +This version is aligned with the ISO\ C standard; this does not affect +compatibility with XPG3 applications. Reliable error detection by this +function was never guaranteed. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncpy\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strcspn.3p b/upstream/archlinux/man3p/strcspn.3p new file mode 100644 index 00000000..525c2ae3 --- /dev/null +++ b/upstream/archlinux/man3p/strcspn.3p @@ -0,0 +1,75 @@ +'\" et +.TH STRCSPN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strcspn +\(em get the length of a complementary substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strcspn(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrcspn\fR() +function shall compute the length (in bytes) of the maximum initial +segment of the string pointed to by +.IR s1 +which consists entirely of bytes +.IR not +from the string pointed to by +.IR s2 . +.SH "RETURN VALUE" +The +\fIstrcspn\fR() +function shall return the length of the computed segment of the string +pointed to by +.IR s1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strdup.3p b/upstream/archlinux/man3p/strdup.3p new file mode 100644 index 00000000..40de016f --- /dev/null +++ b/upstream/archlinux/man3p/strdup.3p @@ -0,0 +1,139 @@ +'\" et +.TH STRDUP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strdup, strndup +\(em duplicate a specific number of bytes from a string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strdup(const char *\fIs\fP); +char *strndup(const char *\fIs\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +The +\fIstrdup\fR() +function shall return a pointer to a new string, which is a duplicate +of the string pointed to by +.IR s . +The returned pointer can be passed to +\fIfree\fR(). +A null pointer is returned if the new string cannot be created. +.P +The +\fIstrndup\fR() +function shall be equivalent to the +\fIstrdup\fR() +function, duplicating the provided +.IR s +in a new block of memory allocated as if by using +\fImalloc\fR(), +with the exception being that +\fIstrndup\fR() +copies at most +.IR size +plus one bytes into the newly allocated memory, terminating the new +string with a NUL character. If the length of +.IR s +is larger than +.IR size , +only +.IR size +bytes shall be duplicated. If +.IR size +is larger than the length of +.IR s , +all bytes in +.IR s +shall be copied into the new memory buffer, including the terminating +NUL character. The newly created string shall always be properly +terminated. +.SH "RETURN VALUE" +The +\fIstrdup\fR() +function shall return a pointer to a new string on success. Otherwise, +it shall return a null pointer and set +.IR errno +to indicate the error. +.P +Upon successful completion, the +\fIstrndup\fR() +function shall return a pointer to the newly allocated memory +containing the duplicated string. Otherwise, it shall return a null +pointer and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR ENOMEM +Storage space available is insufficient. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIstrdup\fR() +and +\fIstrndup\fR(), +this is the return value. +.P +Implementations are free to +\fImalloc\fR() +a buffer containing either (\c +.IR size ++ 1) bytes or (\c +.IR strnlen ( +.IR s , +.IR size ) ++ 1) bytes. Applications should not assume that +\fIstrndup\fR() +will allocate (\c +.IR size ++ 1) bytes when +.IR strlen ( +.IR s ) +is smaller than +.IR size . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fIwcsdup\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strerror.3p b/upstream/archlinux/man3p/strerror.3p new file mode 100644 index 00000000..c15777f4 --- /dev/null +++ b/upstream/archlinux/man3p/strerror.3p @@ -0,0 +1,310 @@ +'\" et +.TH STRERROR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strerror, +strerror_l, +strerror_r +\(em get error message string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strerror(int \fIerrnum\fR); +char *strerror_l(int \fIerrnum\fR, locale_t \fIlocale\fR); +int strerror_r(int \fIerrnum\fR, char *\fIstrerrbuf\fR, size_t \fIbuflen\fR); +.fi +.SH DESCRIPTION +For +\fIstrerror\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrerror\fR() +function shall map the error number in +.IR errnum +to a locale-dependent error message string and shall return a pointer +to it. Typically, the values for +.IR errnum +come from +.IR errno , +but +\fIstrerror\fR() +shall map any value of type +.BR int +to a message. +.P +The application shall not modify the string returned. +The returned string pointer might be invalidated or +the string content might be overwritten by a subsequent call to +\fIstrerror\fR(), +or by a subsequent call to +\fIstrerror_l\fR() +in the same thread. The returned pointer and the string content might +also be invalidated if the calling thread is terminated. +.P +The string may be overwritten by a subsequent call to +\fIstrerror_l\fR() +in the same thread. +.P +The contents of the error message strings returned by +\fIstrerror\fR() +should be determined by the setting of the +.IR LC_MESSAGES +category in the current locale. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 +calls +\fIstrerror\fR(). +.P +The +\fIstrerror\fR() +and +\fIstrerror_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error of +\fIstrerror\fR(), +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrerror\fR(), +then check +.IR errno . +Similarly, since +\fIstrerror_l\fR() +is required to return a string for some errors, an application wishing +to check for all error situations should set +.IR errno +to 0, then call +\fIstrerror_l\fR(), +then check +.IR errno . +.P +The +\fIstrerror\fR() +function need not be thread-safe. +.P +The +\fIstrerror_l\fR() +function shall map the error number in +.IR errnum +to a locale-dependent error message string in the locale represented by +.IR locale +and shall return a pointer to it. +.P +The +\fIstrerror_r\fR() +function shall map the error number in +.IR errnum +to a locale-dependent error message string and shall return the string +in the buffer pointed to by +.IR strerrbuf , +with length +.IR buflen . +.P +If the value of +.IR errnum +is a valid error number, the message string shall indicate what error +occurred; if the value of +.IR errnum +is zero, the message string shall either be an empty string or +indicate that no error occurred; otherwise, if these functions complete +successfully, the message string shall indicate that an unknown error +occurred. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrerror_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon completion, whether successful or not, +\fIstrerror\fR() +shall return a pointer to the generated message string. +On error +.IR errno +may be set, but no return value is reserved to indicate an error. +.P +Upon successful completion, +\fIstrerror_l\fR() +shall return a pointer to the generated message string. If +.IR errnum +is not a valid error number, +.IR errno +may be set to +.BR [EINVAL] , +but a pointer to a message string shall still be returned. If any other +error occurs, +.IR errno +shall be set to indicate the error and a null pointer shall be +returned. +.P +Upon successful completion, +\fIstrerror_r\fR() +shall return 0. Otherwise, an error number shall be returned to +indicate the error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The value of +.IR errnum +is neither a valid error number nor zero. +.P +The +\fIstrerror_r\fR() +function may fail if: +.TP +.BR ERANGE +Insufficient storage was supplied via +.IR strerrbuf +and +.IR buflen +to contain the generated message string. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Historically in some implementations, calls to +\fIperror\fR() +would overwrite the string that the pointer returned by +\fIstrerror\fR() +points to. Such implementations did not conform to the ISO\ C standard; however, +application developers should be aware of this behavior if they wish +their applications to be portable to such implementations. +.SH RATIONALE +The +\fIstrerror_l\fR() +function is required to be thread-safe, thereby eliminating the +need for an equivalent to the +\fIstrerror_r\fR() +function. +.P +Earlier versions of this standard did not explicitly require that the +error message strings returned by +\fIstrerror\fR() +and +\fIstrerror_r\fR() +provide any information about the error. This version of the standard +requires a meaningful message for any successful completion. +.P +Since no return value is reserved to indicate a +\fIstrerror\fR() +error, but all calls (whether successful or not) must return a pointer +to a message string, on error +\fIstrerror\fR() +can return a pointer to an empty string or a pointer to a meaningful +string that can be printed. +.P +Note that the +.BR [EINVAL] +error condition is a may fail error. If an invalid error number is +supplied as the value of +.IR errnum , +applications should be prepared to handle any of the following: +.IP " 1." 4 +Error (with no meaningful message): +.IR errno +is set to +.BR [EINVAL] , +the return value is a pointer to an empty string. +.IP " 2." 4 +Successful completion: +.IR errno +is unchanged and the return value points to a string like +.BR \(dqunknown error\(dq +or +.BR \(dqerror number xxx\(dq +(where +.IR xxx +is the value of +.IR errnum ). +.IP " 3." 4 +Combination of #1 and #2: +.IR errno +is set to +.BR [EINVAL] +and the return value points to a string like +.BR \(dqunknown error\(dq +or +.BR \(dqerror number xxx\(dq +(where +.IR xxx +is the value of +.IR errnum ). +Since applications frequently use the return value of +\fIstrerror\fR() +as an argument to functions like +\fIfprintf\fR() +(without checking the return value) and since applications have no way +to parse an error message string to determine whether +.IR errnum +represents a valid error number, implementations are encouraged to +implement #3. Similarly, implementations are encouraged to have +\fIstrerror_r\fR() +return +.BR [EINVAL] +and put a string like +.BR \(dqunknown error\(dq +or +.BR \(dqerror number xxx\(dq +in the buffer pointed to by +.IR strerrbuf +when the value of +.IR errnum +is not a valid error number. +.P +Some applications rely on being able to set +.IR errno +to 0 before calling a function with no reserved value to indicate an +error, then call +.IR strerror ( errno ) +afterwards to detect whether an error occurred (because +.IR errno +changed) or to indicate success (because +.IR errno +remained zero). This usage pattern requires that +.IR strerror (0) +succeed with useful results. Previous versions of the standard did not +specify the behavior when +.IR errnum +is zero. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIperror\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strfmon.3p b/upstream/archlinux/man3p/strfmon.3p new file mode 100644 index 00000000..f8463e7b --- /dev/null +++ b/upstream/archlinux/man3p/strfmon.3p @@ -0,0 +1,328 @@ +'\" et +.TH STRFMON "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strfmon, +strfmon_l +\(em convert monetary value to a string +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t strfmon(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, ...); +ssize_t strfmon_l(char *restrict \fIs\fP, size_t \fImaxsize\fP, + locale_t \fIlocale\fP, const char *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +The +\fIstrfmon\fR() +function shall place characters into the array pointed to by +.IR s +as controlled by the string pointed to by +.IR format . +No more than +.IR maxsize +bytes are placed into the array. +.P +The format is a character string, beginning and ending in its +initial state, if any, that contains two types of objects: +\fIplain characters\fP, +which are simply copied to the output stream, and \fIconversion +specifications\fP, +each of which shall result in the fetching of zero or more arguments +which are converted and formatted. The results are undefined if there +are insufficient arguments for the format. If the format is exhausted +while arguments remain, the excess arguments are simply ignored. +.P +The application shall ensure that a conversion specification consists +of the following sequence: +.IP " *" 4 +A +.BR '%' +character +.IP " *" 4 +Optional flags +.IP " *" 4 +Optional field width +.IP " *" 4 +Optional left precision +.IP " *" 4 +Optional right precision +.IP " *" 4 +A required conversion specifier character that determines the +conversion to be performed +.P +The +\fIstrfmon_l\fR() +function shall be equivalent to the +\fIstrfmon\fR() +function, except that the locale data used is from the +locale represented by +.IR locale . +.SS Flags +.P +One or more of the following optional flags can be specified to control +the conversion: +.IP "\fR=\fIf\fR" 8 +An +.BR '=' +followed by a single character +.IR f +which is used as the numeric fill character. In order to work with +precision or width counts, the fill character shall be a single byte +character; if not, the behavior is undefined. The default numeric fill +character is the +. +This flag does not affect field width filling which always uses the +. +This flag is ignored unless a left precision (see below) is specified. +.IP "\fR^\fR" 8 +Do not format the currency amount with grouping characters. The +default is to insert the grouping characters if defined for the current +locale. +.IP "\fR+\fR\ or\ \fR(\fR" 8 +Specify the style of representing positive and negative currency +amounts. Only one of +.BR '+' +or +.BR '(' +may be specified. If +.BR '+' +is specified, the locale's equivalent of +.BR '+' +and +.BR '\-' +are used (for example, in many locales, the empty string if positive and +.BR '\-' +if negative). If +.BR '(' +is specified, negative amounts are enclosed within parentheses. If +neither flag is specified, the +.BR '+' +style is used. +.IP "\fR!\fR" 8 +Suppress the currency symbol from the output conversion. +.IP "\fR\-\fR" 8 +Specify the alignment. If this flag is present the result of the +conversion is left-justified (padded to the right) rather than +right-justified. This flag shall be ignored unless a field width (see +below) is specified. +.SS "Field Width" +.IP "\fIw\fP" 8 +A decimal digit string +.IR w +specifying a minimum field width in bytes in which the result of the +conversion is right-justified (or left-justified if the flag +.BR '\-' +is specified). The default is 0. +.SS "Left Precision" +.IP "\fR#\fIn\fR" 8 +A +.BR '#' +followed by a decimal digit string +.IR n +specifying a maximum number of digits expected to be formatted to the +left of the radix character. This option can be used to keep the +formatted output from multiple calls to the +\fIstrfmon\fR() +function aligned in the same columns. It can also be used to fill +unused positions with a special character as in +.BR \(dq$***123.45\(dq . +This option causes an amount to be formatted as if it has the number of +digits specified by +.IR n . +If more than +.IR n +digit positions are required, this conversion specification is ignored. +Digit positions in excess of those actually required are filled with +the numeric fill character (see the \fR=\fIf\fR flag above). +.RS 8 +.P +If grouping has not been suppressed with the +.BR '\(ha' +flag, and it is defined for the current locale, grouping separators are +inserted before the fill characters (if any) are added. Grouping +separators are not applied to fill characters even if the fill +character is a digit. +.P +To ensure alignment, any characters appearing before or after the +number in the formatted output such as currency or sign symbols are +padded as necessary with + +characters to make their positive and negative formats an equal length. +.RE +.SS "Right Precision" +.IP "\fR.\fIp\fR" 8 +A + +followed by a decimal digit string +.IR p +specifying the number of digits after the radix character. If the +value of the right precision +.IR p +is 0, no radix character appears. If a right precision is not +included, a default specified by the current locale is used. The +amount being formatted is rounded to the specified number of digits +prior to formatting. +.SS "Conversion Specifier Characters" +.P +The conversion specifier characters and their meanings are: +.IP "\fRi\fP" 8 +The +.BR double +argument is formatted according to the locale's international currency +format (for example, in the US: USD 1,234.56). If the argument is +\(+-Inf or NaN, the result of the conversion is unspecified. +.IP "\fRn\fP" 8 +The +.BR double +argument is formatted according to the locale's national currency +format (for example, in the US: $1,234.56). If the argument is +\(+-Inf or NaN, the result of the conversion is unspecified. +.IP "\fR%\fP" 8 +Convert to a +.BR '%' ; +no argument is converted. The entire conversion specification shall be +.BR %% . +.SS "Locale Information" +.P +The +.IR LC_MONETARY +category of the current locale affects the behavior of this function +including the monetary radix character (which may be different from the +numeric radix character affected by the +.IR LC_NUMERIC +category), the grouping separator, the currency symbols, and formats. +The international currency symbol should be conformant with the ISO\ 4217:\|2001 standard. +.P +If the value of +.IR maxsize +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrfmon_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +If the total number of resulting bytes including the terminating null +byte is not more than +.IR maxsize , +these functions shall return the number of bytes placed into the array +pointed to by +.IR s , +not including the terminating NUL character. Otherwise, \-1 shall be +returned, the contents of the array are unspecified, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR E2BIG +Conversion stopped due to lack of space in the buffer. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +Given a locale for the US and the values 123.45, \-123.45, and +3456.781, the following output might be produced. Square brackets (\c +.BR \(dq[\|]\(dq ) +are used in this example to delimit the output. +.sp +.RS 4 +.nf + +%n [$123.45] \fRDefault formatting\fP + [-$123.45] + [$3,456.78] +.P +%11n [ $123.45] \fRRight align within an 11-character field\fP + [ -$123.45] + [ $3,456.78] +.P +%#5n [ $ 123.45] \fRAligned columns for values up to 99\|999\fP + [-$ 123.45] + [ $ 3,456.78] +.P +%=*#5n [ $***123.45] \fRSpecify a fill character\fP + [-$***123.45] + [ $*3,456.78] +.P +%=0#5n [ $000123.45] \fRFill characters do not use grouping\fP + [-$000123.45] \fReven if the fill character is a digit\fP + [ $03,456.78] +.P +%\(ha#5n [ $ 123.45] \fRDisable the grouping separator\fP + [-$ 123.45] + [ $ 3456.78] +.P +%\(ha#5.0n [ $ 123] \fRRound off to whole units\fP + [-$ 123] + [ $ 3457] +.P +%\(ha#5.4n [ $ 123.4500] \fRIncrease the precision\fP + [-$ 123.4500] + [ $ 3456.7810] +.P +%(#5n [ $ 123.45 ] \fRUse an alternative pos/neg style\fP + [($ 123.45)] + [ $ 3,456.78 ] +.P +%!(#5n [ 123.45 ] \fRDisable the currency symbol\fP + [( 123.45)] + [ 3,456.78 ] +.P +%-14#5.4n [ $ 123.4500 ] \fRLeft-justify the output\fP + [-$ 123.4500 ] + [ $ 3,456.7810 ] +.P +%14#5.4n [ $ 123.4500] \fRCorresponding right-justified output\fP + [ -$ 123.4500] + [ $ 3,456.7810] +.fi +.P +.RE +.P +See also the EXAMPLES section in +\fIfprintf\fR(). +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +Lowercase conversion characters are reserved for future standards use +and uppercase for implementation-defined use. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strftime.3p b/upstream/archlinux/man3p/strftime.3p new file mode 100644 index 00000000..1a1c4b23 --- /dev/null +++ b/upstream/archlinux/man3p/strftime.3p @@ -0,0 +1,1004 @@ +'\" et +.TH STRFTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strftime, +strftime_l +\(em convert date and time to a string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strftime(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP); +size_t strftime_l(char *restrict \fIs\fP, size_t \fImaxsize\fP, + const char *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIstrftime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrftime\fR() +function shall place bytes into the array pointed to by +.IR s +as controlled by the string pointed to by +.IR format . +The format is a character string, beginning and ending in its initial +shift state, if any. The format string consists of zero or more conversion +specifications and ordinary characters. +.P +Each conversion specification is introduced by the +.BR '%' +character after which the following appear in sequence: +.IP " *" 4 +An optional flag: +.RS 4 +.IP "\fR0\fR" 6 +The zero character (\c +.BR '0' ), +which specifies that the character used as the padding character is +.BR '0' , +.IP "\fR+\fR" 6 +The + +character (\c +.BR '+' ), +which specifies that the character used as the padding character is +.BR '0' , +and that if and only if the field being produced consumes more than four +bytes to represent a year (for +.BR %F , +.BR %G , +or +.BR %Y ) +or more than two bytes to represent the year divided by 100 (for +.BR %C ) +then a leading + +character shall be included if the year being processed is greater than +or equal to zero or a leading + +character (\c +.BR '\-' ) +shall be included if the year is less than zero. +.P +The default padding character is unspecified. +.RE +.IP " *" 4 +An optional minimum field width. If the converted value, including +any leading +.BR '+' +or +.BR '\-' +sign, has fewer bytes than the minimum field width and the padding +character is not the NUL character, the output shall be padded on the left +(after any leading +.BR '+' +or +.BR '\-' +sign) with the padding character. +.IP " *" 4 +An optional +.BR E +or +.BR O +modifier. +.IP " *" 4 +A terminating conversion specifier character that indicates the type of +conversion to be applied. +.P +The results are unspecified if more than one flag character is specified, +a flag character is specified without a minimum field width; a minimum +field width is specified without a flag character; a modifier is specified +with a flag or with a minimum field width; or if a minimum field width +is specified for any conversion specifier other than +.BR C , +.BR F , +.BR G , +or +.BR Y . +.P +All ordinary characters (including the terminating NUL character) +are copied unchanged into the array. If copying takes place between +objects that overlap, the behavior is undefined. No more than maxsize +bytes are placed into the array. Each conversion specifier is replaced by +appropriate characters as described in the following list. The appropriate +characters are determined using the +.IR LC_TIME +category of the current locale and by the values of zero or more members +of the broken-down time structure pointed to by +.IR timeptr , +as specified in brackets in the description. If any of the specified +values are outside the normal range, the characters stored are +unspecified. +.P +The +\fIstrftime_l\fR() +function shall be equivalent to the +\fIstrftime\fR() +function, except that the locale data used is from the +locale represented by +.IR locale . +.P +Local timezone information is used as though +\fIstrftime\fR() +called +\fItzset\fR(). +.P +The following conversion specifiers shall be supported: +.IP "\fRa\fR" 8 +Replaced by the locale's abbreviated weekday name. [\c +.IR tm_wday ] +.IP "\fRA\fR" 8 +Replaced by the locale's full weekday name. [\c +.IR tm_wday ] +.IP "\fRb\fR" 8 +Replaced by the locale's abbreviated month name. [\c +.IR tm_mon ] +.IP "\fRB\fR" 8 +Replaced by the locale's full month name. [\c +.IR tm_mon ] +.IP "\fRc\fR" 8 +Replaced by the locale's appropriate date and time representation. +(See the Base Definitions volume of POSIX.1\(hy2017, +.IR .) +.IP "\fRC\fR" 8 +Replaced by the year divided by 100 and truncated to an integer, +as a decimal number. [\c +.IR tm_year ] +.RS 8 +.P +If a minimum field width is not specified, the number of characters +placed into the array pointed to by +.IR s +will be the number of digits in the year divided by 100 or two, whichever +is greater. +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits in the year divided by 100 or the minimum +field width, whichever is greater. +.RE +.IP "\fRd\fR" 8 +Replaced by the day of the month as a decimal number [01,31]. [\c +.IR tm_mday ] +.IP "\fRD\fR" 8 +Equivalent to +.BR %m /\c +.BR %d /\c +.BR %y . +[\c +.IR tm_mon , +.IR tm_mday , +.IR tm_year ] +.IP "\fRe\fR" 8 +Replaced by the day of the month as a decimal number [1,31]; +a single digit is preceded by a space. [\c +.IR tm_mday ] +.IP "\fRF\fR" 8 +Equivalent to %\*!+4\*?Y-%m-%d if no flag and no minimum field width +are specified. [\c +.IR tm_year , +.IR tm_mon , +.IR tm_mday ] +.RS 8 +.P +If a minimum field width of +.IR x +is specified, the year shall be output as if by the +.BR Y +specifier (described below) with whatever flag was given and a minimum +field width of +.IR x \-6. +If +.IR x +is less than 6, the behavior shall be as if +.IR x +equalled 6. +.P +If the minimum field width is specified to be 10, and the year is +four digits long, then the output string produced will match the +ISO\ 8601:\|2004 standard subclause 4.1.2.2 complete representation, extended format date +representation of a specific day. If a + flag is specified, a minimum +field width of +.IR x +is specified, and +.IR x \-7 +bytes are sufficient to hold the digits of the year (not including any +needed sign character), then the output will match the ISO\ 8601:\|2004 standard subclause +4.1.2.4 complete representation, expanded format date representation of +a specific day. +.RE +.IP "\fRg\fR" 8 +Replaced by the last 2 digits of the week-based year (see below) +as a decimal number [00,99]. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRG\fR" 8 +Replaced by the week-based year (see below) as a decimal number +(for example, 1977). [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.RS 8 +.P +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits and leading sign characters (if any) in +the year, or the minimum field width, whichever is greater. +.RE +.IP "\fRh\fR" 8 +Equivalent to +.BR %b . +[\c +.IR tm_mon ] +.IP "\fRH\fR" 8 +Replaced by the hour (24-hour clock) as a decimal number [00,23]. [\c +.IR tm_hour ] +.IP "\fRI\fR" 8 +Replaced by the hour (12-hour clock) as a decimal number [01,12]. [\c +.IR tm_hour ] +.IP "\fRj\fR" 8 +Replaced by the day of the year as a decimal number [001,366]. [\c +.IR tm_yday ] +.IP "\fRm\fR" 8 +Replaced by the month as a decimal number [01,12]. [\c +.IR tm_mon ] +.IP "\fRM\fR" 8 +Replaced by the minute as a decimal number [00,59]. [\c +.IR tm_min ] +.IP "\fRn\fR" 8 +Replaced by a +. +.IP "\fRp\fR" 8 +Replaced by the locale's equivalent of either a.m. or p.m. [\c +.IR tm_hour ] +.IP "\fRr\fR" 8 +Replaced by the time in a.m. and p.m. notation; +in the POSIX locale this shall be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +[\c +.IR tm_hour , +.IR tm_min , +.IR tm_sec ] +.IP "\fRR\fR" 8 +Replaced by the time in 24-hour notation (\c +.BR %H :\c +.BR %M ). +[\c +.IR tm_hour , +.IR tm_min ] +.IP "\fRS\fR" 8 +Replaced by the second as a decimal number [00,60]. [\c +.IR tm_sec ] +.IP "\fRt\fR" 8 +Replaced by a +. +.IP "\fRT\fR" 8 +Replaced by the time (\c +.BR %H :\c +.BR %M :\c +.BR %S ). +[\c +.IR tm_hour , +.IR tm_min , +.IR tm_sec ] +.IP "\fRu\fR" 8 +Replaced by the weekday as a decimal number [1,7], with 1 representing +Monday. [\c +.IR tm_wday ] +.IP "\fRU\fR" 8 +Replaced by the week number of the year as a decimal number [00,53]. +The first Sunday of January is the first day of week 1; days in the +new year before this are in week 0. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRV\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week) as a decimal number [01,53]. If the week containing 1 January +has four or more days in the new year, then it is considered week 1. +Otherwise, it is the last week of the previous year, and the next week +is week 1. Both January 4th and the first Thursday of January are +always in week 1. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRw\fR" 8 +Replaced by the weekday as a decimal number [0,6], with 0 representing +Sunday. [\c +.IR tm_wday ] +.IP "\fRW\fR" 8 +Replaced by the week number of the year as a decimal number [00,53]. +The first Monday of January is the first day of week 1; days in the new +year before this are in week 0. [\c +.IR tm_year , +.IR tm_wday , +.IR tm_yday ] +.IP "\fRx\fR" 8 +Replaced by the locale's appropriate date representation. (See +the Base Definitions volume of POSIX.1\(hy2017, +.IR .) +.IP "\fRX\fR" 8 +Replaced by the locale's appropriate time representation. (See +the Base Definitions volume of POSIX.1\(hy2017, +.IR .) +.IP "\fRy\fR" 8 +Replaced by the last two digits of the year as a decimal number +[00,99]. [\c +.IR tm_year ] +.IP "\fRY\fR" 8 +Replaced by the year as a decimal number (for example, 1997). [\c +.IR tm_year ] +.RS 8 +.P +If a minimum field width is specified, the number of characters placed +into the array pointed to by +.IR s +will be the number of digits and leading sign characters (if any) in +the year, or the minimum field width, whichever is greater. +.RE +.IP "\fRz\fR" 8 +Replaced by the offset from UTC in the ISO\ 8601:\|2004 standard format (\c +.BR +hhmm +or +.BR \-hhmm ), +or by no characters if no timezone is determinable. For example, +.BR \(dq-0430\(dq +means 4 hours 30 minutes behind UTC (west of Greenwich). +If +.IR tm_isdst +is zero, the standard time offset is used. If +.IR tm_isdst +is greater than zero, the daylight savings time offset is used. If +.IR tm_isdst +is negative, no characters are returned. +[\c +.IR tm_isdst ] +.IP "\fRZ\fR" 8 +Replaced by the timezone name or abbreviation, or by no bytes if no +timezone information exists. [\c +.IR tm_isdst ] +.IP "\fR%\fR" 8 +Replaced by +.BR % . +.P +If a conversion specification does not correspond to any of the above, +the behavior is undefined. +.P +If a +.BR "struct tm" +broken-down time structure is created by +\fIlocaltime\fR() +or +\fIlocaltime_r\fR(), +or modified by +\fImktime\fR(), +and the value of +.IR TZ +is subsequently modified, the results of the +.BR %Z +and +.BR %z +\fIstrftime\fR() +conversion specifiers are undefined, when +\fIstrftime\fR() +is called with such a broken-down time structure. +.P +If a +.BR "struct tm" +broken-down time structure is created or modified by +\fIgmtime\fR() +or +\fIgmtime_r\fR(), +it is unspecified whether the result of the +.BR %Z +and +.BR %z +conversion specifiers shall refer to UTC or the current local timezone, +when +\fIstrftime\fR() +is called with such a broken-down time structure. +.SS "Modified Conversion Specifiers" +.P +Some conversion specifiers can be modified by the +.BR E +or +.BR O +modifier characters to indicate that an alternative format or +specification should be used rather than the one normally used by the +unmodified conversion specifier. If the alternative format or +specification does not exist for the current locale (see ERA in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 7.3.5" ", " "LC_TIME"), +the behavior shall be as if the unmodified conversion +specification were used. +.IP "\fR%Ec\fR" 8 +Replaced by the locale's alternative appropriate date and time +representation. +.IP "\fR%EC\fR" 8 +Replaced by the name of the base year (period) in the locale's +alternative representation. +.IP "\fR%Ex\fR" 8 +Replaced by the locale's alternative date representation. +.IP "\fR%EX\fR" 8 +Replaced by the locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +Replaced by the offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +Replaced by the full alternative year representation. +.IP "\fR%Od\fR" 8 +Replaced by the day of the month, using the locale's alternative +numeric symbols, filled as needed with leading zeros if there is any +alternative symbol for zero; otherwise, with leading + +characters. +.IP "\fR%Oe\fR" 8 +Replaced by the day of the month, using the locale's alternative +numeric symbols, filled as needed with leading + +characters. +.IP "\fR%OH\fR" 8 +Replaced by the hour (24-hour clock) using the locale's alternative +numeric symbols. +.IP "\fR%OI\fR" 8 +Replaced by the hour (12-hour clock) using the locale's alternative +numeric symbols. +.IP "\fR%Om\fR" 8 +Replaced by the month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +Replaced by the minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +Replaced by the seconds using the locale's alternative numeric symbols. +.IP "\fR%Ou\fR" 8 +Replaced by the weekday as a number in the locale's alternative +representation (Monday=1). +.IP "\fR%OU\fR" 8 +Replaced by the week number of the year (Sunday as the first day of the +week, rules corresponding to +.BR %U ) +using the locale's alternative numeric symbols. +.IP "\fR%OV\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week, rules corresponding to +.BR %V ) +using the locale's alternative numeric symbols. +.IP "\fR%Ow\fR" 8 +Replaced by the number of the weekday (Sunday=0) using the locale's +alternative numeric symbols. +.IP "\fR%OW\fR" 8 +Replaced by the week number of the year (Monday as the first day of the +week) using the locale's alternative numeric symbols. +.IP "\fR%Oy\fR" 8 +Replaced by the year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.P +.BR %g , +.BR %G , +and +.BR %V +give values according to the ISO\ 8601:\|2004 standard week-based year. In this system, +weeks begin on a Monday and week 1 of the year is the week that +includes January 4th, which is also the week that includes the first +Thursday of the year, and is also the first week that contains at least +four days in the year. If the first Monday of January is the 2nd, 3rd, +or 4th, the preceding days are part of the last week of the preceding +year; thus, for Saturday 2nd January 1999, +.BR %G +is replaced by 1998 and +.BR %V +is replaced by 53. If December 29th, 30th, or 31st is a Monday, it and +any following days are part of week 1 of the following year. Thus, for +Tuesday 30th December 1997, +.BR %G +is replaced by 1998 and +.BR %V +is replaced by 01. +.P +If a conversion specifier is not one of the above, the behavior is +undefined. +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrftime_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +If the total number of resulting bytes including the terminating null +byte is not more than +.IR maxsize , +these functions shall return the number of bytes placed into the array +pointed to by +.IR s , +not including the terminating NUL character. Otherwise, 0 shall be returned +and the contents of the array are unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting a Localized Date String" +.P +The following example first sets the locale to the user's default. The +locale information will be used in the +\fInl_langinfo\fR() +and +\fIstrftime\fR() +functions. The +\fInl_langinfo\fR() +function returns the localized date string which specifies how the date +is laid out. The +\fIstrftime\fR() +function takes this information and, using the +.BR tm +structure for values, places the date and time information into +.IR datestring . +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +struct tm *tm; +char datestring[256]; +\&... +setlocale (LC_ALL, ""); +\&... +strftime (datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +The range of values for +.BR %S +is [00,60] rather than [00,59] to allow for the occasional leap +second. +.P +Some of the conversion specifications are duplicates of others. They +are included for compatibility with +\fInl_cxtime\fR() +and +\fInl_ascxtime\fR(), +which were published in Issue 2. +.P +The +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y +format specifiers in +\fIstrftime\fR() +always print full values, but the +\fIstrptime\fR() +.BR %C , +.BR %F , +and +.BR %Y +format specifiers only scan two digits (assumed to be the first two +digits of a four-digit year) for +.BR %C +and four digits (assumed to be the entire (four-digit) year) for +.BR %F +and +.BR %Y . +This mimics the behavior of +\fIprintf\fR() +and +\fIscanf\fR(); +that is: +.sp +.RS 4 +.nf + +printf("%2d", x = 1000); +.fi +.P +.RE +.P +prints +.BR \(dq1000\(dq , +but: +.sp +.RS 4 +.nf + +scanf(%2d", &x); +.fi +.P +.RE +.P +when given +.BR \(dq1000\(dq +as input will only store 10 in +.IR x ). +Applications using extended ranges of years must be sure that the number +of digits specified for scanning years with +\fIstrptime\fR() +matches the number of digits that will actually be present in the input +stream. Historic implementations of the +.BR %Y +conversion specification (with no flags and no minimum field width) +produced different output formats. Some always produced at least four +digits (with 0 fill for years from 0 through 999) while others only +produced the number of digits present in the year (with no fill and no +padding). These two forms can be produced with the +.BR '0' +flag and a minimum field width options using the conversions +specifications +.BR %04Y +and +.BR %01Y , +respectively. +.P +In the past, the C and POSIX standards specified that +.BR %F +produced an ISO\ 8601:\|2004 standard date format, but didn't specify which one. For +years in the range [0001,9999], POSIX.1\(hy2008 requires that the output +produced match the ISO\ 8601:\|2004 standard complete representation extended format +(YYYY-MM-DD) and for years outside of this range produce output +that matches the ISO\ 8601:\|2004 standard expanded representation extended format +(<+/->YYYYY-MM-DD). To fully meet ISO\ 8601:\|2004 standard +requirements, the producer and consumer must agree on a date format that +has a specific number of bytes reserved to hold the characters used to +represent the years that is sufficiently large to hold all values that +will be shared. For example, the +.BR %+13F +conversion specification will produce output matching the format +.BR \(dq<+/->YYYYYY-MM-DD\(dq +(a leading +.BR '+' +or +.BR '\-' +sign; a six-digit, 0-filled year; a +.BR '\-' ; +a two-digit, leading 0-filled month; another +.BR '\-' ; +and the two-digit, leading 0-filled day within the month). +.P +Note that if the year being printed is greater than 9999, the resulting +string from the unadorned +.BR %F +conversion specifications will not conform to the ISO\ 8601:\|2004 standard extended format, +complete representation for a date and will instead be an extended format, +expanded representation (presumably without the required agreement +between the date's producer and consumer). +.P +In the C or POSIX locale, the +.BR E +and +.BR O +modifiers are ignored and the replacement strings for the following +specifiers are: +.IP "\fR%a\fR" 8 +The first three characters of +.BR %A . +.IP "\fR%A\fR" 8 +One of Sunday, Monday, .\|.\|., Saturday. +.IP "\fR%b\fR" 8 +The first three characters of +.BR %B . +.IP "\fR%B\fR" 8 +One of January, February, .\|.\|., December. +.IP "\fR%c\fR" 8 +Equivalent to +.BR %a +.BR %b +.BR %e +.BR %T +.BR %Y . +.IP "\fR%p\fR" 8 +One of AM or PM. +.IP "\fR%r\fR" 8 +Equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fR%x\fR" 8 +Equivalent to +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fR%X\fR" 8 +Equivalent to +.BR %T . +.IP "\fR%Z\fR" 8 +Implementation-defined. +.SH RATIONALE +The +.BR %Y +conversion specification to +\fIstrftime\fR() +was frequently assumed to be a four-digit year, but the ISO\ C standard does not +specify that +.BR %Y +is restricted to any subset of allowed values from the +.IR tm_year +field. Similarly, the +.BR %C +conversion specification was assumed to be a two-digit field and the +first part of the output from the +.BR %F +conversion specification was assumed to be a four-digit field. With +.IR tm_year +being a signed 32 or more-bit +.BR int +and with many current implementations supporting 64-bit +.BR time_t +types in one or more programming environments, these assumptions are +clearly wrong. +.P +POSIX.1\(hy2008 now allows the format specifications +.BR %0xC , +.BR %0xF , +.BR %0xG , +and +.BR %0xY +(where +.BR 'x' +is a string of decimal digits used to specify printing and scanning of a +string of +.IR x +decimal digits) with leading zero fill characters. Allowing applications +to set the field width enables them to agree on the number of digits +to be printed and scanned in the ISO\ 8601:\|2004 standard expanded representation of a +year (for +.BR %F , +.BR %G , +and +.BR %Y ) +or all but the last two digits of the year (for +.BR %C ). +This is based on a feature in some versions of GNU +.BR libc 's +\fIstrftime\fR(). +The GNU version allows specifying space, zero, or no-fill characters in +\fIstrftime\fR() +format strings, but does not allow any flags to be specified in +\fIstrptime\fR() +format strings. These implementations also allow these flags to be +specified for any numeric field. POSIX.1\(hy2008 only requires the zero fill flag +(\c +.BR '0' ) +and only requires that it be recognized when processing +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y +specifications when a minimum field width is also specified. The +.BR '0' +flag is the only flag needed to produce and scan the ISO\ 8601:\|2004 standard +year fields using the extended format forms. POSIX.1\(hy2008 also allows +applications to specify the same flag and field width specifiers to be +used in both +\fIstrftime\fR() +and +\fIstrptime\fR() +format strings for symmetry. Systems may provide other flag characters +and may accept flags in conjunction with conversion specifiers other than +.BR %C , +.BR %F , +.BR %G , +and +.BR %Y ; +but portable applications cannot depend on such extensions. +.P +POSIX.1\(hy2008 now also allows the format specifications +.BR %+xC , +.BR %+xF , +.BR %+xG , +and +.BR %+xY +(where +.BR 'x' +is a string of decimal digits used to specify printing and scanning of +a string of +.BR 'x' +decimal digits) with leading zero fill characters and a leading +.BR '+' +sign character if the year being converted is more than four digits +or a minimum field width is specified that allows room for more than +four digits for the year. This allows date providers and consumers to +agree on a specific number of digits to represent a year as required by +the ISO\ 8601:\|2004 standard expanded representation formats. The expanded representation +formats all require the year to begin with a leading +.BR '+' +or +.BR '\-' +sign. +(All of these specifiers can also provide a leading +.BR '\-' +sign for negative years. Since negative years and the year 0 don't fit +well with the Gregorian or Julian calendars, the normal ranges of dates +start with year 1. The ISO\ C standard allows +.IR tm_year +to assume values corresponding to years before year 1, but the use of +such years provided unspecified results.) +.P +Some earlier version of this standard specified that applications wanting +to use +\fIstrptime\fR() +to scan dates and times printed by +\fIstrftime\fR() +should provide non-digit characters between fields to separate years +from months and days. It also supported +.BR %F +to print and scan the ISO\ 8601:\|2004 standard extended format, complete representation date +for years 1 through 9999 (i.e., YYYY-MM-DD). However, many applications +were written to print (using +\fIstrftime\fR()) +and scan (using +\fIstrptime\fR()) +dates written using the basic format complete representation +(four-digit years) and truncated representation (two-digit years) +specified by the ISO\ 8601:\|2004 standard representation of dates and times which do not +have any separation characters between fields. The ISO\ 8601:\|2004 standard also specifies +basic format expanded representation where the creator and consumer of +these fields agree beforehand to represent years as leading zero-filled +strings of an agreed length of more than four digits to represent a year +(again with no separation characters when year, month, and day are all +displayed). Applications producing and consuming expanded representations +are encouraged to use the +.BR '+' +flag and an appropriate maximum field width to scan the year including +the leading sign. Note that even without the +.BR '+' +flag, years less than zero may be represented with a leading + +for +.BR %F , +.BR %G , +and +.BR %Y +conversion specifications. Using negative years results in unspecified +behavior. +.P +If a format specification +.BR %+xF +with the field width +.IR x +greater than 11 is specified and the width is large enough to display +the full year, the output string produced will match the ISO\ 8601:\|2004 standard +subclause 4.1.2.4 expanded representation, extended format date +representation for a specific day. (For years in the range [1,99\|999], +.BR %+12F +is sufficient for an agreed five-digit year with a leading sign using +the ISO\ 8601:\|2004 standard expanded representation, extended format for a specific day +.BR \(dq<+/->YYYYY-MM-DD\(dq .) +Note also that years less than 0 may produce a leading + +character (\c +.BR '\-' ) +when using +.BR %Y +or +.BR %C +whether or not the +.BR '0' +or +.BR '+' +flags are used. +.P +The difference between the +.BR '0' +flag and the +.BR '+' +flag is whether the leading +.BR '+' +character will be provided for years >9999 as required for the ISO\ 8601:\|2004 standard +extended representation format containing a year. For example: +.TS +box center tab(!); +cB | cB | cB | cB +cB | cB | cB | cB +l | lf5 | l | l. +!!\fIstrftime\fP(\^)!\fIstrptime\fP(\^) +Year!Conversion Specification!Output!Scan Back +_ +1970!%Y!1970!1970 +_ +1970!%+4Y!1970!1970 +_ +27!%Y!27 or 0027!27 +_ +270!%Y!270 or 0270!270 +_ +270!%+4Y!0270!270 +_ +17!%C%y!0017!17 +_ +270!%C%y!0270!270 +_ +12345!%Y!12345!1234* +_ +12345!%+4Y!+12345!123* +_ +12345!%05Y!12345!12345 +_ +270!%+5Y \fRor\fP %+3C%y!+0270!270 +_ +12345!%+5Y \fRor\fP %+3C%y!+12345!1234* +_ +12345!%06Y \fRor\fP %04C%y!012345!12345 +_ +12345!%+6Y \fRor\fP %+4C%y!+12345!12345 +_ +123456!%08Y \fRor\fP %06C%y!00123456!123456 +_ +123456!%+8Y \fRor\fP %+6C%y!+0123456!123456 +.TE +.P +In the cases above marked with a * in the +\fIstrptime\fR() +scan back field, the implied or specified number of characters scanned by +\fIstrptime\fR() +was less than the number of characters output by +\fIstrftime\fR() +using the same format; so the remaining digits of the year were dropped +when the output date produced by +\fIstrftime\fR() +was scanned back in by +\fIstrptime\fR(). +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgetdate\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItzset\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 7.3.5" ", " "LC_TIME", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strlen.3p b/upstream/archlinux/man3p/strlen.3p new file mode 100644 index 00000000..6082b6e0 --- /dev/null +++ b/upstream/archlinux/man3p/strlen.3p @@ -0,0 +1,131 @@ +'\" et +.TH STRLEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strlen, strnlen +\(em get length of fixed size string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strlen(const char *\fIs\fP); +size_t strnlen(const char *\fIs\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +For +\fIstrlen\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrlen\fR() +function shall compute the number of bytes in the string to which +.IR s +points, not including the terminating NUL character. +.P +The +\fIstrnlen\fR() +function shall compute the smaller of the number of bytes in the array +to which +.IR s +points, not including any terminating NUL character, or the value of the +.IR maxlen +argument. The +\fIstrnlen\fR() +function shall never examine more than +.IR maxlen +bytes of the array pointed to by +.IR s . +.SH "RETURN VALUE" +The +\fIstrlen\fR() +function shall return the length of +.IR s ; +no return value shall be reserved to indicate an error. +.P +The +\fIstrnlen\fR() +function shall return the number of bytes preceding the first null +byte in the array to which +.IR s +points, if +.IR s +contains a null byte within the first +.IR maxlen +bytes; otherwise, it shall return +.IR maxlen . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting String Lengths" +.P +The following example sets the maximum length of +.IR key +and +.IR data +by using +\fIstrlen\fR() +to get the lengths of those strings. +.sp +.RS 4 +.nf + +#include +\&... +struct element { + char *key; + char *data; +}; +\&... +char *key, *data; +int len; +.P +*keylength = *datalength = 0; +\&... +if ((len = strlen(key)) > *keylength) + *keylength = len; +if ((len = strlen(data)) > *datalength) + *datalength = len; +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcslen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strncasecmp.3p b/upstream/archlinux/man3p/strncasecmp.3p new file mode 100644 index 00000000..891ed327 --- /dev/null +++ b/upstream/archlinux/man3p/strncasecmp.3p @@ -0,0 +1,43 @@ +'\" et +.TH STRNCASECMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strncasecmp, +strncasecmp_l +\(em case-insensitive string comparisons +.SH SYNOPSIS +.LP +.nf +#include +.P +int strncasecmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP); +int strncasecmp_l(const char *\fIs1\fP, const char *\fIs2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrcasecmp\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strncat.3p b/upstream/archlinux/man3p/strncat.3p new file mode 100644 index 00000000..fbb988f4 --- /dev/null +++ b/upstream/archlinux/man3p/strncat.3p @@ -0,0 +1,80 @@ +'\" et +.TH STRNCAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strncat +\(em concatenate a string with part of another +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strncat(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrncat\fR() +function shall append not more than +.IR n +bytes (a NUL character and bytes that follow it are not appended) +from the array pointed to by +.IR s2 +to the end of the string pointed to by +.IR s1 . +The initial byte of +.IR s2 +overwrites the NUL character at the end of +.IR s1 . +A terminating NUL character is always appended to the result. If copying +takes place between objects that overlap, the behavior is undefined. +.SH "RETURN VALUE" +The +\fIstrncat\fR() +function shall return +.IR s1 ; +no return value shall be reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strncmp.3p b/upstream/archlinux/man3p/strncmp.3p new file mode 100644 index 00000000..54c864ce --- /dev/null +++ b/upstream/archlinux/man3p/strncmp.3p @@ -0,0 +1,84 @@ +'\" et +.TH STRNCMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strncmp +\(em compare part of two strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int strncmp(const char *\fIs1\fP, const char *\fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrncmp\fR() +function shall compare not more than +.IR n +bytes (bytes that follow a NUL character are not compared) from the array +pointed to by +.IR s1 +to the array pointed to by +.IR s2 . +.P +The sign of a non-zero return value is determined by the sign of the +difference between the values of the first pair of bytes (both +interpreted as type +.BR "unsigned char" ) +that differ in the strings being compared. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrncmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +possibly null-terminated array pointed to by +.IR s1 +is greater than, equal to, or less than the possibly null-terminated +array pointed to by +.IR s2 +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strncpy.3p b/upstream/archlinux/man3p/strncpy.3p new file mode 100644 index 00000000..4fbde2d0 --- /dev/null +++ b/upstream/archlinux/man3p/strncpy.3p @@ -0,0 +1,118 @@ +'\" et +.TH STRNCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +stpncpy, strncpy +\(em copy fixed length string, returning a pointer to the array end +.SH SYNOPSIS +.LP +.nf +#include +.P +char *stpncpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +char *strncpy(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +For +\fIstrncpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstpncpy\fR() +and +\fIstrncpy\fR() +functions shall copy not more than +.IR n +bytes (bytes that follow a NUL character are not copied) from the array +pointed to by +.IR s2 +to the array pointed to by +.IR s1 . +.P +If the array pointed to by +.IR s2 +is a string that is shorter than +.IR n +bytes, NUL characters shall be appended to the copy in the array +pointed to by +.IR s1 , +until +.IR n +bytes in all are written. +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +If a NUL character is written to the destination, the +\fIstpncpy\fR() +function shall return the address of the first such NUL character. +Otherwise, it shall return +.IR &s1 [ n ]. +.P +The +\fIstrncpy\fR() +function shall return +.IR s1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications must provide the space in +.IR s1 +for the +.IR n +bytes to be transferred, as well as ensure that the +.IR s2 +and +.IR s1 +arrays do not overlap. +.P +Character movement is performed differently in different +implementations. Thus, overlapping moves may yield surprises. +.P +If there is no NUL character byte in the first +.IR n +bytes of the array pointed to by +.IR s2 , +the result is not null-terminated. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIwcsncpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strndup.3p b/upstream/archlinux/man3p/strndup.3p new file mode 100644 index 00000000..61a05d88 --- /dev/null +++ b/upstream/archlinux/man3p/strndup.3p @@ -0,0 +1,40 @@ +'\" et +.TH STRNDUP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strndup +\(em duplicate a specific number of bytes from a string +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strndup(const char *\fIs\fP, size_t \fIsize\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrdup\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strnlen.3p b/upstream/archlinux/man3p/strnlen.3p new file mode 100644 index 00000000..4b5b3e9e --- /dev/null +++ b/upstream/archlinux/man3p/strnlen.3p @@ -0,0 +1,40 @@ +'\" et +.TH STRNLEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strnlen +\(em get length of fixed size string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strnlen(const char *\fIs\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrlen\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strpbrk.3p b/upstream/archlinux/man3p/strpbrk.3p new file mode 100644 index 00000000..c62652c4 --- /dev/null +++ b/upstream/archlinux/man3p/strpbrk.3p @@ -0,0 +1,73 @@ +'\" et +.TH STRPBRK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strpbrk +\(em scan a string for a byte +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strpbrk(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrpbrk\fR() +function shall locate the first occurrence in the string pointed to by +.IR s1 +of any byte from the string pointed to by +.IR s2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIstrpbrk\fR() +shall return a pointer to the byte or a null pointer if no byte from +.IR s2 +occurs in +.IR s1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrchr\fR\^(\|)", +.IR "\fIstrrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strptime.3p b/upstream/archlinux/man3p/strptime.3p new file mode 100644 index 00000000..9c974915 --- /dev/null +++ b/upstream/archlinux/man3p/strptime.3p @@ -0,0 +1,443 @@ +'\" et +.TH STRPTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strptime +\(em date and time conversion +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strptime(const char *restrict \fIbuf\fP, const char *restrict \fIformat\fP, + struct tm *restrict \fItm\fP); +.fi +.SH DESCRIPTION +The +\fIstrptime\fR() +function shall convert the character string pointed to by +.IR buf +to values which are stored in the +.BR tm +structure pointed to by +.IR tm , +using the format specified by +.IR format . +.P +The format is composed of zero or more directives. Each directive is +composed of one of the following: one or more white-space characters +(as specified by +\fIisspace\fR()); +an ordinary character (neither +.BR '%' +nor a white-space character); or a conversion specification. +.P +Each conversion specification is introduced by the +.BR '%' +character after which the following appear in sequence: +.IP " *" 4 +An optional flag, the zero character (\c +.BR '0' ) +or the + +character (\c +.BR '+' ), +which is ignored. +.IP " *" 4 +An optional field width. If a field width is specified, it shall be +interpreted as a string of decimal digits that will determine the maximum +number of bytes converted for the conversion rather than the number of +bytes specified below in the description of the conversion specifiers. +.IP " *" 4 +An optional +.BR E +or +.BR O +modifier. +.IP " *" 4 +A terminating conversion specifier character that indicates the type of +conversion to be applied. +.P +The conversions are determined using the +.IR LC_TIME +category of the current locale. The application shall ensure that +there is white-space or other non-alphanumeric characters between any +two conversion specifications unless all of the adjacent conversion +specifications convert a known, fixed number of characters. In the +following list, the maximum number of characters scanned (excluding the +one matching the next directive) is as follows: +.IP " *" 4 +If a maximum field width is specified, then that number +.IP " *" 4 +Otherwise, the pattern +.BR \(dq{x}\(dq +indicates that the maximum is +.IR x +.IP " *" 4 +Otherwise, the pattern +.BR \(dq[x,y]\(dq +indicates that the value shall fall within the range given (both bounds +being inclusive), and the maximum number of characters scanned shall be +the maximum required to represent any value in the range without leading +zeros and without a leading + +.P +The following conversion specifiers are supported. +.P +The results are unspecified if a modifier is specified with a flag or +with a minimum field width, or if a field width is specified for any +conversion specifier other than +.BR C +or +.BR Y . +.IP "\fRa\fR" 8 +The day of the week, using the locale's weekday names; either the +abbreviated or full name may be specified. +.IP "\fRA\fR" 8 +Equivalent to +.BR %a . +.IP "\fRb\fR" 8 +The month, using the locale's month names; either the abbreviated or +full name may be specified. +.IP "\fRB\fR" 8 +Equivalent to +.BR %b . +.IP "\fRc\fR" 8 +Replaced by the locale's appropriate date and time representation. +.IP "\fRC\fR" 8 +All but the last two digits of the year {2}; leading zeros shall be +permitted but shall not be required. A leading +.BR '+' +or +.BR '\-' +character shall be permitted before any leading zeros but shall not +be required. +.IP "\fRd\fR" 8 +The day of the month [01,31]; leading zeros shall be permitted but shall +not be required. +.IP "\fRD\fR" 8 +The date as +.BR %m /\c +.BR %d /\c +.BR %y . +.IP "\fRe\fR" 8 +Equivalent to +.BR %d . +.IP "\fRh\fR" 8 +Equivalent to +.BR %b . +.IP "\fRH\fR" 8 +The hour (24-hour clock) [00,23]; leading zeros shall be permitted but +shall not be required. +.IP "\fRI\fR" 8 +The hour (12-hour clock) [01,12]; leading zeros shall be permitted but +shall not be required. +.IP "\fRj\fR" 8 +The day number of the year [001,366]; leading zeros shall be permitted +but shall not be required. +.IP "\fRm\fR" 8 +The month number [01,12]; leading zeros shall be permitted but shall +not be required. +.IP "\fRM\fR" 8 +The minute [00,59]; leading zeros shall be permitted but shall not +be required. +.IP "\fRn\fR" 8 +Any white space. +.IP "\fRp\fR" 8 +The locale's equivalent of a.m. or p.m. +.IP "\fRr\fR" 8 +12-hour clock time using the AM/PM notation if +.BR t_fmt_ampm +is not an empty string in the +.IR LC_TIME +portion of the current locale; in the POSIX locale, this shall +be equivalent to +.BR %I :\c +.BR %M :\c +.BR %S +.BR %p . +.IP "\fRR\fR" 8 +The time as +.BR %H :\c +.BR %M . +.IP "\fRS\fR" 8 +The seconds [00,60]; leading zeros shall be permitted but shall +not be required. +.IP "\fRt\fR" 8 +Any white space. +.IP "\fRT\fR" 8 +The time as +.BR %H :\c +.BR %M :\c +.BR %S . +.IP "\fRU\fR" 8 +The week number of the year (Sunday as the first day of the week) as a +decimal number [00,53]; leading zeros shall be permitted but shall +not be required. +.IP "\fRw\fR" 8 +The weekday as a decimal number [0,6], with 0 representing Sunday. +.IP "\fRW\fR" 8 +The week number of the year (Monday as the first day of the week) as a +decimal number [00,53]; leading zeros shall be permitted but shall +not be required. +.IP "\fRx\fR" 8 +The date, using the locale's date format. +.IP "\fRX\fR" 8 +The time, using the locale's time format. +.IP "\fRy\fR" 8 +The last two digits of the year. When +.IR format +contains neither a +.BR C +conversion specifier nor a +.BR Y +conversion specifier, values in the range [69,99] shall refer to years +1969 to 1999 inclusive and values in the range [00,68] shall refer to +years 2000 to 2068 inclusive; leading zeros shall be permitted but shall +not be required. A leading +.BR '+' +or +.BR '\-' +character shall be permitted before any leading zeros but shall not +be required. +.RS 8 +.TP 10 +.BR Note: +It is expected that in a future version of this standard the default +century inferred from a 2-digit year will change. (This would apply +to all commands accepting a 2-digit year as input.) +.P +.RE +.IP "\fRY\fR" 8 +The full year {4}; leading zeros shall be permitted but shall +not be required. A leading +.BR '+' +or +.BR '\-' +character shall be permitted before any leading zeros but shall not +be required. +.IP "\fR%\fP" 8 +Replaced by +.BR % . +.SS "Modified Conversion Specifiers" +.P +Some conversion specifiers can be modified by the +.BR E +and +.BR O +modifier characters to indicate that an alternative format or +specification should be used rather than the one normally used by the +unmodified conversion specifier. If the alternative format or +specification does not exist in the current locale, the behavior shall +be as if the unmodified conversion specification were used. +.IP "\fR%Ec\fR" 8 +The locale's alternative appropriate date and time representation. +.IP "\fR%EC\fR" 8 +The name of the base year (period) in the locale's alternative +representation. +.IP "\fR%Ex\fR" 8 +The locale's alternative date representation. +.IP "\fR%EX\fR" 8 +The locale's alternative time representation. +.IP "\fR%Ey\fR" 8 +The offset from +.BR %EC +(year only) in the locale's alternative representation. +.IP "\fR%EY\fR" 8 +The full alternative year representation. +.IP "\fR%Od\fR" 8 +The day of the month using the locale's alternative numeric symbols; +leading zeros shall be permitted but shall not be required. +.IP "\fR%Oe\fR" 8 +Equivalent to +.BR %Od . +.IP "\fR%OH\fR" 8 +The hour (24-hour clock) using the locale's alternative numeric +symbols. +.IP "\fR%OI\fR" 8 +The hour (12-hour clock) using the locale's alternative numeric +symbols. +.IP "\fR%Om\fR" 8 +The month using the locale's alternative numeric symbols. +.IP "\fR%OM\fR" 8 +The minutes using the locale's alternative numeric symbols. +.IP "\fR%OS\fR" 8 +The seconds using the locale's alternative numeric symbols. +.IP "\fR%OU\fR" 8 +The week number of the year (Sunday as the first day of the week) using +the locale's alternative numeric symbols. +.IP "\fR%Ow\fR" 8 +The number of the weekday (Sunday=0) using the locale's alternative +numeric symbols. +.IP "\fR%OW\fR" 8 +The week number of the year (Monday as the first day of the week) using +the locale's alternative numeric symbols. +.IP "\fR%Oy\fR" 8 +The year (offset from +.BR %C ) +using the locale's alternative numeric symbols. +.P +A conversion specification composed of white-space characters is +executed by scanning input up to the first character that is not +white-space (which remains unscanned), or until no more characters can +be scanned. +.P +A conversion specification that is an ordinary character is executed by +scanning the next character from the buffer. If the character scanned +from the buffer differs from the one comprising the directive, the +directive fails, and the differing and subsequent characters remain +unscanned. +.P +A series of conversion specifications composed of +.BR %n , +.BR %t , +white-space characters, or any combination is executed by scanning up +to the first character that is not white space (which remains +unscanned), or until no more characters can be scanned. +.P +Any other conversion specification is executed by scanning characters +until a character matching the next directive is scanned, or until no +more characters can be scanned. These characters, except the one +matching the next directive, are then compared to the locale values +associated with the conversion specifier. If a match is found, values +for the appropriate +.BR tm +structure members are set to values corresponding to the locale +information. Case is ignored when matching items in +.IR buf +such as month or weekday names. If no match is found, +\fIstrptime\fR() +fails and no more characters are scanned. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrptime\fR() +shall return a pointer to the character following the last character +parsed. Otherwise, a null pointer shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Convert a Date-Plus-Time String to Broken-Down Time and Then into Seconds" +.P +The following example demonstrates the use of +\fIstrptime\fR() +to convert a string into broken-down time. The broken-down time is then +converted into seconds since the Epoch using +\fImktime\fR(). +.sp +.RS 4 +.nf + +#include +\&... +.P +struct tm tm; +time_t t; +.P +if (strptime("6 Dec 2001 12:33:45", "%d %b %Y %H:%M:%S", &tm) == NULL) + /* Handle error */; +.P +printf("year: %d; month: %d; day: %d;\en", + tm.tm_year, tm.tm_mon, tm.tm_mday); +printf("hour: %d; minute: %d; second: %d\en", + tm.tm_hour, tm.tm_min, tm.tm_sec); +printf("week day: %d; year day: %d\en", tm.tm_wday, tm.tm_yday); +.P +tm.tm_isdst = -1; /* Not set by strptime(); tells mktime() + to determine whether daylight saving time + is in effect */ +t = mktime(&tm); +if (t == -1) + /* Handle error */; +printf("seconds since the Epoch: %ld\en", (long) t);" +.fi +.P +.RE +.SH "APPLICATION USAGE" +Several ``equivalent to'' formats and the special processing of +white-space characters are provided in order to ease the use of +identical +.IR format +strings for +\fIstrftime\fR() +and +\fIstrptime\fR(). +.P +It should be noted that dates constructed by the +\fIstrftime\fR() +function with the +.BR %Y +or +.BR %C%y +conversion specifiers may have values larger than 9\|999. If the +\fIstrptime\fR() +function is used to read such values using +.BR %C%y +or +.BR %Y , +the year values will be truncated to four digits. Applications should use +.BR %+ \c +.IR w \c +.BR %y +or +.BR %+ \c +.IR x \c +.BR Y +with +.IR w +and +.IR x +set large enough to contain the full value of any years that will be +printed or scanned. +.P +See also the APPLICATION USAGE section in +.IR "\fIstrftime\fR\^(\|)". +.P +It is unspecified whether multiple calls to +\fIstrptime\fR() +using the same +.BR tm +structure will update the current contents of the structure or +overwrite all contents of the structure. Conforming applications +should make a single call to +\fIstrptime\fR() +with a format and all data needed to completely specify the date and +time being converted. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIstrftime\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfprintf\fR\^(\|)", +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fItime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strrchr.3p b/upstream/archlinux/man3p/strrchr.3p new file mode 100644 index 00000000..37f89ece --- /dev/null +++ b/upstream/archlinux/man3p/strrchr.3p @@ -0,0 +1,99 @@ +'\" et +.TH STRRCHR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strrchr +\(em string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strrchr(const char *\fIs\fP, int \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrrchr\fR() +function shall locate the last occurrence of +.IR c +(converted to a +.BR char ) +in the string pointed to by +.IR s . +The terminating NUL character is considered to be part of the string. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrrchr\fR() +shall return a pointer to the byte or a null pointer if +.IR c +does not occur in the string. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Finding the Base Name of a File" +.P +The following example uses +\fIstrrchr\fR() +to get a pointer to the base name of a file. The +\fIstrrchr\fR() +function searches backwards through the name of the file to find the +last +.BR '/' +character in +.IR name . +This pointer (plus one) will point to the base name of the file. +.sp +.RS 4 +.nf + +#include +\&... +const char *name; +char *basename; +\&... +basename = strrchr(name, \(aq/\(aq) + 1; +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strsignal.3p b/upstream/archlinux/man3p/strsignal.3p new file mode 100644 index 00000000..50de32f2 --- /dev/null +++ b/upstream/archlinux/man3p/strsignal.3p @@ -0,0 +1,108 @@ +'\" et +.TH STRSIGNAL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strsignal +\(em get name of signal +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strsignal(int \fIsignum\fP); +.fi +.SH DESCRIPTION +The +\fIstrsignal\fR() +function shall map the signal number in +.IR signum +to an implementation-defined string and shall return a pointer to it. +It shall use the same set of messages as the +\fIpsignal\fR() +function. +.P +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIstrsignal\fR() +or +\fIsetlocale\fR(). +The returned pointer might also be invalidated if the calling thread +is terminated. +.P +The contents of the message strings returned by +\fIstrsignal\fR() +should be determined by the setting of the +.IR LC_MESSAGES +category in the current locale. +.P +The implementation shall behave as if no function defined in this +standard calls +\fIstrsignal\fR(). +.P +Since no return value is reserved to indicate an error, an application +wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrsignal\fR(), +then check +.IR errno . +.P +The +\fIstrsignal\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrsignal\fR() +shall return a pointer to a string. Otherwise, if +.IR signum +is not a valid signal number, the return value is unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If +.IR signum +is not a valid signal number, some implementations return NULL, while +for others the +\fIstrsignal\fR() +function returns a pointer to a string containing an unspecified +message denoting an unknown signal. POSIX.1\(hy2008 leaves this return +value unspecified. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIpsiginfo\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strspn.3p b/upstream/archlinux/man3p/strspn.3p new file mode 100644 index 00000000..2808c299 --- /dev/null +++ b/upstream/archlinux/man3p/strspn.3p @@ -0,0 +1,71 @@ +'\" et +.TH STRSPN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strspn +\(em get length of a substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strspn(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrspn\fR() +function shall compute the length (in bytes) of the maximum initial +segment of the string pointed to by +.IR s1 +which consists entirely of bytes from the string pointed to by +.IR s2 . +.SH "RETURN VALUE" +The +\fIstrspn\fR() +function shall return the computed length; no return value is reserved +to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strstr.3p b/upstream/archlinux/man3p/strstr.3p new file mode 100644 index 00000000..188f77a6 --- /dev/null +++ b/upstream/archlinux/man3p/strstr.3p @@ -0,0 +1,76 @@ +'\" et +.TH STRSTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strstr +\(em find a substring +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strstr(const char *\fIs1\fP, const char *\fIs2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrstr\fR() +function shall locate the first occurrence in the string pointed to by +.IR s1 +of the sequence of bytes (excluding the terminating NUL character) in the +string pointed to by +.IR s2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIstrstr\fR() +shall return a pointer to the located string or a null pointer if the +string is not found. +.P +If +.IR s2 +points to a string with zero length, the function shall return +.IR s1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtod.3p b/upstream/archlinux/man3p/strtod.3p new file mode 100644 index 00000000..82628211 --- /dev/null +++ b/upstream/archlinux/man3p/strtod.3p @@ -0,0 +1,345 @@ +'\" et +.TH STRTOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtod, +strtof, +strtold +\(em convert a string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double strtod(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +float strtof(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +long double strtold(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the string pointed +to by +.IR nptr +to +.BR double , +.BR float , +and +.BR "long double" +representation, respectively. First, they decompose the input string +into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by +\fIisspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as a floating-point constant or +representing infinity or NaN +.IP " 3." 4 +A final string of one or more unrecognized characters, including the +terminating NUL character of the input string +.P +Then they shall attempt to convert the subject sequence to a +floating-point number, and return the result. +.P +The expected form of the subject sequence is an optional +.BR '+' +or +.BR '\-' +sign, then one of the following: +.IP " *" 4 +A non-empty sequence of decimal digits optionally containing a radix +character; then an optional exponent part consisting of the character +.BR 'e' +or the character +.BR 'E' , +optionally followed by a +.BR '+' +or +.BR '\-' +character, and then followed by one or more decimal digits +.IP " *" 4 +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character; then an optional binary exponent part +consisting of the character +.BR 'p' +or the character +.BR 'P' , +optionally followed by a +.BR '+' +or +.BR '\-' +character, and then followed by one or more decimal digits +.IP " *" 4 +One of INF or INFINITY, ignoring case +.IP " *" 4 +One of NAN or NAN(\fIn-char-sequence\s-3\dopt\u\s+3\fR), ignoring case in +the NAN part, where: +.RS 4 +.sp +.RS 4 +.nf + +n-char-sequence: + digit + nondigit + n-char-sequence digit + n-char-sequence nondigit +.fi +.P +.RE +.RE +.P +The subject sequence is defined as the longest initial subsequence of +the input string, starting with the first non-white-space character, +that is of the expected form. The subject sequence contains no +characters if the input string is not of the expected form. +.P +If the subject sequence has the expected form for a floating-point +number, the sequence of characters starting with the first digit or the +decimal-point character (whichever occurs first) shall be interpreted +as a floating constant of the C language, except that the radix +character shall be used in place of a period, and that if neither an +exponent part nor a radix character appears in a decimal floating-point +number, or if a binary exponent part does not appear in a hexadecimal +floating-point number, an exponent part of the appropriate type with +value zero is assumed to follow the last digit in the string. If the +subject sequence begins with a +, +the sequence shall be +interpreted as negated. A character sequence INF or INFINITY shall be +interpreted as an infinity, if representable in the return type, else +as if it were a floating constant that is too large for the range of +the return type. A character sequence NAN or +NAN(\fIn-char-sequence\s-3\dopt\u\s+3\fR) shall be interpreted as a +quiet NaN, if supported in the return type, else as if it were a +subject sequence part that does not have the expected form; the meaning +of the \fIn\fR-char sequences is implementation-defined. A pointer to +the final string is stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +If the subject sequence has the hexadecimal form and FLT_RADIX is a +power of 2, the value resulting from the conversion is correctly +rounded. +.P +The radix character is defined in the current locale (category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +In other than the C +or POSIX +locale, additional locale-specific subject sequence forms may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +is stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0 is returned on error and is also a valid return on success, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrtod\fR(), +\fIstrtof\fR(), +or +\fIstrtold\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value. If no conversion could be performed, 0 shall be returned, and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +\(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL shall be returned +(according to the sign of the value), and +.IR errno +shall be set to +.BR [ERANGE] . +.P +If the correct value would cause an underflow, a value whose magnitude +is no greater than the smallest normalized positive number in the +return type shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR ERANGE +The value to be returned would cause overflow +or underflow. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the subject sequence has the hexadecimal form and FLT_RADIX is not a +power of 2, and the result is not exactly representable, the result +should be one of the two numbers in the appropriate internal format +that are adjacent to the hexadecimal floating source value, with the +extra stipulation that the error should have a correct sign for the +current rounding direction. +.P +If the subject sequence has the decimal form and at most DECIMAL_DIG +(defined in +.IR ) +significant digits, the result should be correctly rounded. If the +subject sequence +.IR D +has the decimal form and more than DECIMAL_DIG significant digits, +consider the two bounding, adjacent decimal strings +.IR L +and +.IR U , +both having DECIMAL_DIG significant digits, such that the values of +.IR L , +.IR D , +and +.IR U +satisfy +.IR L +<= +.IR D +<= +.IR U . +The result should be one of the (equal or adjacent) values that would +be obtained by correctly rounding +.IR L +and +.IR U +according to the current rounding direction, with the extra stipulation +that the error with respect to +.IR D +should have a correct sign for the current rounding direction. +.P +The changes to +\fIstrtod\fR() +introduced by the ISO/IEC\ 9899:\|1999 standard can alter the behavior of well-formed +applications complying with the ISO/IEC\ 9899:\|1990 standard and thus earlier versions of +this standard. One such example would be: +.sp +.RS 4 +.nf + +int +what_kind_of_number (char *s) +{ + char *endp; + double d; + long l; +.P + d = strtod(s, &endp); + if (s != endp && *endp == `\e0\(aq) + printf("It\(aqs a float with value %g\en", d); + else + { + l = strtol(s, &endp, 0); + if (s != endp && *endp == `\e0\(aq) + printf("It\(aqs an integer with value %ld\en", 1); + else + return 1; + } + return 0; +} +.fi +.P +.RE +.P +If the function is called with: +.sp +.RS 4 +.nf + +what_kind_of_number ("0x10") +.fi +.P +.RE +.P +an ISO/IEC\ 9899:\|1990 standard-compliant library will result in the function printing: +.sp +.RS 4 +.nf + +It\(aqs an integer with value 16 +.fi +.P +.RE +.P +With the ISO/IEC\ 9899:\|1999 standard, the result is: +.sp +.RS 4 +.nf + +It\(aqs a float with value 16 +.fi +.P +.RE +.P +The change in behavior is due to the inclusion of floating-point +numbers in hexadecimal notation without requiring that either a decimal +point or the binary exponent be present. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisspace\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtoimax.3p b/upstream/archlinux/man3p/strtoimax.3p new file mode 100644 index 00000000..c4335732 --- /dev/null +++ b/upstream/archlinux/man3p/strtoimax.3p @@ -0,0 +1,125 @@ +'\" et +.TH STRTOIMAX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtoimax, +strtoumax +\(em convert string to integer type +.SH SYNOPSIS +.LP +.nf +#include +.P +intmax_t strtoimax(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +uintmax_t strtoumax(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall be equivalent to the +\fIstrtol\fR(), +\fIstrtoll\fR(), +\fIstrtoul\fR(), +and +\fIstrtoull\fR() +functions, except that the initial portion of the string shall be +converted to +.BR intmax_t +and +.BR uintmax_t +representation, respectively. +.SH "RETURN VALUE" +These functions shall return the converted value, if any. +.P +If no conversion could be performed, zero shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the value of +.IR base +is not supported, 0 shall be returned and +.IR errno +shall be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +{INTMAX_MAX}, +{INTMAX_MIN}, +or +{UINTMAX_MAX} +shall be returned (according to the return type and sign of the value, +if any), and +.IR errno +shall be set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the value of +.IR *endptr +is unspecified if the value of +.IR base +is not supported, applications should either ensure that +.IR base +has a supported value (0 or between 2 and 36) before the call, or check +for an +.BR [EINVAL] +error before examining +.IR *endptr . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrtol\fR\^(\|)", +.IR "\fIstrtoul\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtok.3p b/upstream/archlinux/man3p/strtok.3p new file mode 100644 index 00000000..78af67ac --- /dev/null +++ b/upstream/archlinux/man3p/strtok.3p @@ -0,0 +1,232 @@ +'\" et +.TH STRTOK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtok, +strtok_r +\(em split string into tokens +.SH SYNOPSIS +.LP +.nf +#include +.P +char *strtok(char *restrict \fIs\fP, const char *restrict \fIsep\fP); +char *strtok_r(char *restrict \fIs\fP, const char *restrict \fIsep\fP, + char **restrict \fIstate\fP); +.fi +.SH DESCRIPTION +For +\fIstrtok\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +A sequence of calls to +\fIstrtok\fR() +breaks the string pointed to by +.IR s +into a sequence of tokens, each of which is delimited by a byte from +the string pointed to by +.IR sep . +The first call in the sequence has +.IR s +as its first argument, and is followed by calls with a null pointer as +their first argument. The separator string pointed to by +.IR sep +may be different from call to call. +.P +The first call in the sequence searches the string pointed to by +.IR s +for the first byte that is +.IR not +contained in the current separator string pointed to by +.IR sep . +If no such byte is found, then there are no tokens in the string +pointed to by +.IR s +and +\fIstrtok\fR() +shall return a null pointer. If such a byte is found, it is the +start of the first token. +.P +The +\fIstrtok\fR() +function then searches from there for a byte that +.IR is +contained in the current separator string. If no such byte is found, +the current token extends to the end of the string pointed to by +.IR s , +and subsequent searches for a token shall return a null pointer. If +such a byte is found, it is overwritten by a NUL character, which +terminates the current token. The +\fIstrtok\fR() +function saves a pointer to the following byte, from which the next +search for a token shall start. +.P +Each subsequent call, with a null pointer as the value of the first +argument, starts searching from the saved pointer and behaves as +described above. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 +calls +\fIstrtok\fR(). +.P +The +\fIstrtok\fR() +function need not be thread-safe. +.P +The +\fIstrtok_r\fR() +function shall be equivalent to +\fIstrtok\fR(), +except that +\fIstrtok_r\fR() +shall be thread-safe and the argument +.IR state +points to a user-provided pointer that allows +\fIstrtok_r\fR() +to maintain state between calls which scan the same string. The +application shall ensure that the pointer pointed to by +.IR state +is unique for each string (\c +.IR s ) +being processed concurrently by +\fIstrtok_r\fR() +calls. The application need not initialize the pointer pointed to by +.IR state +to any particular value. The implementation shall not update the +pointer pointed to by +.IR state +to point (directly or indirectly) to resources, other than within +the string +.IR s , +that need to be freed or released by the caller. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrtok\fR() +shall return a pointer to the first byte of a token. Otherwise, +if there is no token, +\fIstrtok\fR() +shall return a null pointer. +.P +The +\fIstrtok_r\fR() +function shall return a pointer to the token found, or a null pointer +when no token is found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Searching for Word Separators" +.P +The following example searches for tokens separated by + +characters. +.sp +.RS 4 +.nf + +#include +\&... +char *token; +char line[] = "LINE TO BE SEPARATED"; +char *search = " "; +.P +/* Token will point to "LINE". */ +token = strtok(line, search); +.P +/* Token will point to "TO". */ +token = strtok(NULL, search); +.fi +.P +.RE +.SS "Find First two Fields in a Buffer" +.P +The following example uses +\fIstrtok\fR() +to find two character strings (a key and data associated with that key) +separated by any combination of +, +, +or + +characters at the start of the array of characters pointed to by +.IR buffer . +.sp +.RS 4 +.nf + +#include +\&... +char *buffer; +\&... +struct element { + char *key; + char *data; +} e; +\&... +// Load the buffer... +\&... +// Get the key and its data... +e.key = strtok(buffer, " \et\en"); +e.data = strtok(NULL, " \et\en"); +// Process the rest of the contents of the buffer... +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +Note that if +.IR sep +is the empty string, +\fIstrtok\fR() +and +\fIstrtok_r\fR() +return a pointer to the remainder of the string being tokenized. +.P +The +\fIstrtok_r\fR() +function is thread-safe and stores its state in a user-supplied buffer +instead of possibly using a static data area that may be overwritten +by an unrelated call from another thread. +.SH RATIONALE +The +\fIstrtok\fR() +function searches for a separator string within a larger string. It +returns a pointer to the last substring between separator strings. +This function uses static storage to keep track of the current string +position between calls. The new function, +\fIstrtok_r\fR(), +takes an additional argument, +.IR state , +to keep track of the current position in the string. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtol.3p b/upstream/archlinux/man3p/strtol.3p new file mode 100644 index 00000000..174e0fcc --- /dev/null +++ b/upstream/archlinux/man3p/strtol.3p @@ -0,0 +1,248 @@ +'\" et +.TH STRTOL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtol, +strtoll +\(em convert a string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long strtol(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, int \fIbase\fP); +long long strtoll(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP) +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the string pointed +to by +.IR nptr +to a type +.BR "long" +and +.BR "long long" +representation, respectively. First, they decompose the input string +into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by +\fIisspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final string of one or more unrecognized characters, including +the terminating NUL character of the input string. +.P +Then they shall attempt to convert the subject sequence to an +integer, and return the result. +.P +If the value of +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\-' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\-' +sign. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +are permitted. If the value of +.IR base +is 16, the characters 0x or 0X may optionally precede the sequence of +letters and digits, following the sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input string, starting with the first non-white-space character +that is of the expected form. The subject sequence shall contain no +characters if the input string is empty or consists entirely of +white-space characters, or if the first non-white-space character is +other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and the value of +.IR base +is 0, the sequence of characters starting with the first digit shall be +interpreted as an integer constant. If the subject sequence has the +expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a +, +the value resulting from the +conversion shall be negated. A pointer to the final string shall be +stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locale, additional locale-specific subject sequence forms may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion is performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{LONG_MIN} +or +{LLONG_MIN}, +and +{LONG_MAX} +or +{LLONG_MAX} +are returned on error and are also valid returns on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrtol\fR() +or +\fIstrtoll\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the value of +.IR base +is not supported, 0 shall be returned and +.IR errno +shall be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +{LONG_MIN}, +{LONG_MAX}, +{LLONG_MIN}, +or +{LLONG_MAX} +shall be returned (according to the sign of the value), and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the value of +.IR *endptr +is unspecified if the value of +.IR base +is not supported, applications should either ensure that +.IR base +has a supported value (0 or between 2 and 36) before the call, or check +for an +.BR [EINVAL] +error before examining +.IR *endptr . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtold.3p b/upstream/archlinux/man3p/strtold.3p new file mode 100644 index 00000000..7d6d0def --- /dev/null +++ b/upstream/archlinux/man3p/strtold.3p @@ -0,0 +1,40 @@ +'\" et +.TH STRTOLD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtold +\(em convert a string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +long double strtold(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrtod\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtoll.3p b/upstream/archlinux/man3p/strtoll.3p new file mode 100644 index 00000000..cc881762 --- /dev/null +++ b/upstream/archlinux/man3p/strtoll.3p @@ -0,0 +1,41 @@ +'\" et +.TH STRTOLL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtoll +\(em convert a string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long long strtoll(const char *restrict \fIstr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrtol\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtoul.3p b/upstream/archlinux/man3p/strtoul.3p new file mode 100644 index 00000000..8e060411 --- /dev/null +++ b/upstream/archlinux/man3p/strtoul.3p @@ -0,0 +1,244 @@ +'\" et +.TH STRTOUL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtoul, +strtoull +\(em convert a string to an unsigned long +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned long strtoul(const char *restrict \fIstr\fP, + char **restrict \fIendptr\fP, int \fIbase\fP); +unsigned long long strtoull(const char *restrict \fIstr\fP, + char **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the string pointed +to by +.IR str +to a type +.BR "unsigned long" +and +.BR "unsigned long long" +representation, respectively. First, they decompose the input string +into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space characters (as +specified by +\fIisspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final string of one or more unrecognized characters, including +the terminating NUL character of the input string +.P +Then they shall attempt to convert the subject sequence to an +unsigned integer, and return the result. +.P +If the value of +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\-' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\-' +sign. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +are permitted. If the value of +.IR base +is 16, the characters 0x or 0X may optionally precede the sequence of +letters and digits, following the sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input string, starting with the first non-white-space character +that is of the expected form. The subject sequence shall contain no +characters if the input string is empty or consists entirely of +white-space characters, or if the first non-white-space character is +other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and the value of +.IR base +is 0, the sequence of characters starting with the first digit shall be +interpreted as an integer constant. If the subject sequence has the +expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a +, +the value resulting from the +conversion shall be negated. A pointer to the final string shall be +stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locale, additional locale-specific subject sequence forms may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR str +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{ULONG_MAX}, +and +{ULLONG_MAX} +are returned on error and are also valid returns on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrtoul\fR() +or +\fIstrtoull\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the value of +.IR base +is not supported, 0 shall be returned and +.IR errno +shall be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +{ULONG_MAX} +or +{ULLONG_MAX} +shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the value of +.IR *endptr +is unspecified if the value of +.IR base +is not supported, applications should either ensure that +.IR base +has a supported value (0 or between 2 and 36) before the call, or check +for an +.BR [EINVAL] +error before examining +.IR *endptr . +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIisalpha\fR\^(\|)", +.IR "\fIstrtod\fR\^(\|)", +.IR "\fIstrtol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strtoumax.3p b/upstream/archlinux/man3p/strtoumax.3p new file mode 100644 index 00000000..daad10c7 --- /dev/null +++ b/upstream/archlinux/man3p/strtoumax.3p @@ -0,0 +1,41 @@ +'\" et +.TH STRTOUMAX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strtoumax +\(em convert a string to an integer type +.SH SYNOPSIS +.LP +.nf +#include +.P +uintmax_t strtoumax(const char *restrict \fInptr\fP, char **restrict \fIendptr\fP, + int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIstrtoimax\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/strxfrm.3p b/upstream/archlinux/man3p/strxfrm.3p new file mode 100644 index 00000000..e4d2dfc5 --- /dev/null +++ b/upstream/archlinux/man3p/strxfrm.3p @@ -0,0 +1,156 @@ +'\" et +.TH STRXFRM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +strxfrm, +strxfrm_l +\(em string transformation +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t strxfrm(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, size_t \fIn\fP); +size_t strxfrm_l(char *restrict \fIs1\fP, const char *restrict \fIs2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIstrxfrm\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +functions shall transform the string pointed to by +.IR s2 +and place the resulting string into the array pointed to by +.IR s1 . +The transformation is such that if +\fIstrcmp\fR() +is applied to two transformed strings, it shall return a value greater +than, equal to, or less than 0, corresponding to the result of +\fIstrcoll\fR() +or +\fIstrcoll_l\fR(), +respectively, applied to the same two original strings +with the same locale. +No more than +.IR n +bytes are placed into the resulting array pointed to by +.IR s1 , +including the terminating NUL character. If +.IR n +is 0, +.IR s1 +is permitted to be a null pointer. If copying takes place between +objects that overlap, the behavior is undefined. +.P +The +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIstrxfrm\fR() +or +\fIstrxfrm_l\fR(), +then check +.IR errno . +.P +The behavior is undefined if the +.IR locale +argument to +\fIstrxfrm_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +shall return the length of the transformed string (not including the +terminating NUL character). If the value returned is +.IR n +or more, the contents of the array pointed to by +.IR s1 +are unspecified. +.P +On error, +\fIstrxfrm\fR() +and +\fIstrxfrm_l\fR() +may set +.IR errno +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The string pointed to by the +.IR s2 +argument contains characters outside the domain of the collating +sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The transformation function is such that two transformed strings can be +ordered by +\fIstrcmp\fR() +as appropriate to collating sequence information in the +current locale (category +.IR LC_COLLATE ). +.P +The fact that when +.IR n +is 0 +.IR s1 +is permitted to be a null pointer is useful to determine the size of +the +.IR s1 +array prior to making the transformation. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcmp\fR\^(\|)", +.IR "\fIstrcoll\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/swab.3p b/upstream/archlinux/man3p/swab.3p new file mode 100644 index 00000000..44661b01 --- /dev/null +++ b/upstream/archlinux/man3p/swab.3p @@ -0,0 +1,79 @@ +'\" et +.TH SWAB "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +swab +\(em swap bytes +.SH SYNOPSIS +.LP +.nf +#include +.P +void swab(const void *restrict \fIsrc\fP, void *restrict \fIdest\fP, + ssize_t \fInbytes\fP); +.fi +.SH DESCRIPTION +The +\fIswab\fR() +function shall copy +.IR nbytes +bytes, which are pointed to by +.IR src , +to the object pointed to by +.IR dest , +exchanging adjacent bytes. The +.IR nbytes +argument should be even. If +.IR nbytes +is odd, +\fIswab\fR() +copies and exchanges +.IR nbytes \-1 +bytes and the disposition of the last byte is unspecified. If copying +takes place between objects that overlap, the behavior is undefined. +If +.IR nbytes +is negative, +\fIswab\fR() +does nothing. +.SH "RETURN VALUE" +None. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/swprintf.3p b/upstream/archlinux/man3p/swprintf.3p new file mode 100644 index 00000000..2841ac7d --- /dev/null +++ b/upstream/archlinux/man3p/swprintf.3p @@ -0,0 +1,42 @@ +'\" et +.TH SWPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +swprintf +\(em print formatted wide-character output +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int swprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/swscanf.3p b/upstream/archlinux/man3p/swscanf.3p new file mode 100644 index 00000000..dbd17582 --- /dev/null +++ b/upstream/archlinux/man3p/swscanf.3p @@ -0,0 +1,42 @@ +'\" et +.TH SWSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +swscanf +\(em convert formatted wide-character input +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int swscanf(const wchar_t *restrict \fIws\fP, + const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/symlink.3p b/upstream/archlinux/man3p/symlink.3p new file mode 100644 index 00000000..701baae2 --- /dev/null +++ b/upstream/archlinux/man3p/symlink.3p @@ -0,0 +1,287 @@ +'\" et +.TH SYMLINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +symlink, symlinkat +\(em make a symbolic link +.SH SYNOPSIS +.LP +.nf +#include +.P +int symlink(const char *\fIpath1\fP, const char *\fIpath2\fP); +.P +#include +.P +int symlinkat(const char *\fIpath1\fP, int \fIfd\fP, const char *\fIpath2\fP); +.fi +.SH DESCRIPTION +The +\fIsymlink\fR() +function shall create a symbolic link called +.IR path2 +that contains the string pointed to by +.IR path1 +(\c +.IR path2 +is the name of the symbolic link created, +.IR path1 +is the string contained in the symbolic link). +.P +The string pointed to by +.IR path1 +shall be treated only as a string and shall not be validated +as a pathname. +.P +If the +\fIsymlink\fR() +function fails for any reason other than +.BR [EIO] , +any file named by +.IR path2 +shall be unaffected. +.P +If +.IR path2 +names a symbolic link, +\fIsymlink\fR() +shall fail and set +.IR errno +to +.BR [EEXIST] . +.P +The symbolic link's user ID shall be set to the process' effective +user ID. The symbolic link's group ID shall be set to the group +ID of the parent directory or to the effective group ID of the +process. Implementations shall provide a way to initialize the symbolic +link's group ID to the group ID of the parent directory. Implementations +may, but need not, provide an implementation-defined way to initialize the +symbolic link's group ID to the effective group ID of the calling process. +.P +The values of the file mode bits for the created symbolic link are +unspecified. All interfaces specified by POSIX.1\(hy2008 shall behave as if the +contents of symbolic links can always be read, except that the value of +the file mode bits returned in the +.IR st_mode +field of the +.BR stat +structure is unspecified. +.P +Upon successful completion, +\fIsymlink\fR() +shall mark for update the last data access, last data modification, +and last file status change timestamps of the symbolic link. Also, +the last data modification and last file status change timestamps of +the directory that contains the new entry shall be marked for update. +.P +The +\fIsymlinkat\fR() +function shall be equivalent to the +\fIsymlink\fR() +function except in the case where +.IR path2 +specifies a relative path. In this case the symbolic link is created +relative to the directory associated with the file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +If +\fIsymlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIsymlink\fR(). +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. +Otherwise, these functions shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EACCES +Write permission is denied in the directory where the symbolic link is +being created, or search permission is denied for a component of the +path prefix of +.IR path2 . +.TP +.BR EEXIST +The +.IR path2 +argument names an existing file. +.TP +.BR EIO +An I/O error occurs while reading from or writing to the file system. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of the pathname specified by the +.IR path2 +argument is longer than +{NAME_MAX} +or the length of the +.IR path1 +argument is longer than +{SYMLINK_MAX}. +.TP +.BR ENOENT +A component of the path prefix of +.IR path2 +does not name an existing file or +.IR path2 +is an empty string. +.TP +.BR ENOENT " or " ENOTDIR +.br +The +.IR path2 +argument contains at least one non-\c + +character and ends with one or more trailing + +characters. If +.IR path2 +without the trailing + +characters would name an existing file, an +.BR [ENOENT] +error shall not occur. +.TP +.BR ENOSPC +The directory in which the entry for the new symbolic link is being +placed cannot be extended because no space is left on the file system +containing the directory, or the new symbolic link cannot be created +because no space is left on the file system which shall contain the +link, or the file system is out of file-allocation resources. +.TP +.BR ENOTDIR +A component of the path prefix of +.IR path2 +names an existing file that is neither a directory nor a symbolic link +to a directory. +.TP +.BR EROFS +The new symbolic link would reside on a read-only file system. +.P +The +\fIsymlinkat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path2 +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path2 +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.P +These functions may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path2 +argument. +.TP +.BR ENAMETOOLONG +.br +The length of the +.IR path2 +argument exceeds +{PATH_MAX} +or pathname resolution of a symbolic link in the +.IR path2 +argument produced an intermediate result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Like a hard link, a symbolic link allows a file to have multiple +logical names. The presence of a hard link guarantees the existence of +a file, even after the original name has been removed. A symbolic link +provides no such assurance; in fact, the file named by the +.IR path1 +argument need not exist when the link is created. A symbolic link can +cross file system boundaries. +.P +Normal permission checks are made on each component of the symbolic +link pathname during its resolution. +.SH RATIONALE +The purpose of the +\fIsymlinkat\fR() +function is to create symbolic links in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIsymlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIsymlinkat\fR() +function it can be guaranteed that the created symbolic link is located +relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIlchown\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIreadlink\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sync.3p b/upstream/archlinux/man3p/sync.3p new file mode 100644 index 00000000..fa4e4ec3 --- /dev/null +++ b/upstream/archlinux/man3p/sync.3p @@ -0,0 +1,67 @@ +'\" et +.TH SYNC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sync +\(em schedule file system updates +.SH SYNOPSIS +.LP +.nf +#include +.P +void sync(void); +.fi +.SH DESCRIPTION +The +\fIsync\fR() +function shall cause all information in memory that updates file +systems to be scheduled for writing out to all file systems. +.P +The writing, although scheduled, is not necessarily complete upon +return from +\fIsync\fR(). +.SH "RETURN VALUE" +The +\fIsync\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfsync\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/sysconf.3p b/upstream/archlinux/man3p/sysconf.3p new file mode 100644 index 00000000..606266b8 --- /dev/null +++ b/upstream/archlinux/man3p/sysconf.3p @@ -0,0 +1,359 @@ +'\" et +.TH SYSCONF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +sysconf +\(em get configurable system variables +.SH SYNOPSIS +.LP +.nf +#include +.P +long sysconf(int \fIname\fP); +.fi +.SH DESCRIPTION +The +\fIsysconf\fR() +function provides a method for the application to determine the current +value of a configurable system limit or option (\c +.IR variable ). +The implementation shall support all of the variables listed in the +following table and may support others. +.P +The +.IR name +argument represents the system variable to be queried. The following +table lists the minimal set of system variables from +.IR +or +.IR +that can be returned by +\fIsysconf\fR(), +and the symbolic constants defined in +.IR +that are the corresponding values used for +.IR name . +.ad l +.TS +box center tab(@); +cB | cB +lw(2.7i)1e | le. +Variable@Value of Name +_ +{AIO_LISTIO_MAX}@_SC_AIO_LISTIO_MAX +{AIO_MAX}@_SC_AIO_MAX +{AIO_PRIO_DELTA_MAX}@_SC_AIO_PRIO_DELTA_MAX +{ARG_MAX}@_SC_ARG_MAX +{ATEXIT_MAX}@_SC_ATEXIT_MAX +{BC_BASE_MAX}@_SC_BC_BASE_MAX +{BC_DIM_MAX}@_SC_BC_DIM_MAX +{BC_SCALE_MAX}@_SC_BC_SCALE_MAX +{BC_STRING_MAX}@_SC_BC_STRING_MAX +{CHILD_MAX}@_SC_CHILD_MAX +Clock ticks/second@_SC_CLK_TCK +{COLL_WEIGHTS_MAX}@_SC_COLL_WEIGHTS_MAX +{DELAYTIMER_MAX}@_SC_DELAYTIMER_MAX +{EXPR_NEST_MAX}@_SC_EXPR_NEST_MAX +{HOST_NAME_MAX}@_SC_HOST_NAME_MAX +{IOV_MAX}@_SC_IOV_MAX +{LINE_MAX}@_SC_LINE_MAX +{LOGIN_NAME_MAX}@_SC_LOGIN_NAME_MAX +{NGROUPS_MAX}@_SC_NGROUPS_MAX +Initial size of \fIgetgrgid_r\fP\^(\|) and@_SC_GETGR_R_SIZE_MAX +\fIgetgrnam_r\fP\^(\|) data buffers +Initial size of \fIgetpwuid_r\fP\^(\|) and@_SC_GETPW_R_SIZE_MAX +\fIgetpwnam_r\fP\^(\|) data buffers +{MQ_OPEN_MAX}@_SC_MQ_OPEN_MAX +{MQ_PRIO_MAX}@_SC_MQ_PRIO_MAX +{OPEN_MAX}@_SC_OPEN_MAX +{PAGE_SIZE}@_SC_PAGE_SIZE +{PAGESIZE}@_SC_PAGESIZE +{PTHREAD_DESTRUCTOR_ITERATIONS}@_SC_THREAD_DESTRUCTOR_ITERATIONS +{PTHREAD_KEYS_MAX}@_SC_THREAD_KEYS_MAX +{PTHREAD_STACK_MIN}@_SC_THREAD_STACK_MIN +{PTHREAD_THREADS_MAX}@_SC_THREAD_THREADS_MAX +{RE_DUP_MAX}@_SC_RE_DUP_MAX +{RTSIG_MAX}@_SC_RTSIG_MAX +{SEM_NSEMS_MAX}@_SC_SEM_NSEMS_MAX +{SEM_VALUE_MAX}@_SC_SEM_VALUE_MAX +{SIGQUEUE_MAX}@_SC_SIGQUEUE_MAX +{STREAM_MAX}@_SC_STREAM_MAX +{SYMLOOP_MAX}@_SC_SYMLOOP_MAX +{TIMER_MAX}@_SC_TIMER_MAX +{TTY_NAME_MAX}@_SC_TTY_NAME_MAX +{TZNAME_MAX}@_SC_TZNAME_MAX +_POSIX_ADVISORY_INFO@_SC_ADVISORY_INFO +_POSIX_BARRIERS@_SC_BARRIERS +_POSIX_ASYNCHRONOUS_IO@_SC_ASYNCHRONOUS_IO +_POSIX_CLOCK_SELECTION@_SC_CLOCK_SELECTION +_POSIX_CPUTIME@_SC_CPUTIME +_POSIX_FSYNC@_SC_FSYNC +_POSIX_IPV6@_SC_IPV6 +_POSIX_JOB_CONTROL@_SC_JOB_CONTROL +_POSIX_MAPPED_FILES@_SC_MAPPED_FILES +_POSIX_MEMLOCK@_SC_MEMLOCK +_POSIX_MEMLOCK_RANGE@_SC_MEMLOCK_RANGE +_POSIX_MEMORY_PROTECTION@_SC_MEMORY_PROTECTION +_POSIX_MESSAGE_PASSING@_SC_MESSAGE_PASSING +_POSIX_MONOTONIC_CLOCK@_SC_MONOTONIC_CLOCK +_POSIX_PRIORITIZED_IO@_SC_PRIORITIZED_IO +_POSIX_PRIORITY_SCHEDULING@_SC_PRIORITY_SCHEDULING +_POSIX_RAW_SOCKETS@_SC_RAW_SOCKETS +_POSIX_READER_WRITER_LOCKS@_SC_READER_WRITER_LOCKS +_POSIX_REALTIME_SIGNALS@_SC_REALTIME_SIGNALS +_POSIX_REGEXP@_SC_REGEXP +_POSIX_SAVED_IDS@_SC_SAVED_IDS +_POSIX_SEMAPHORES@_SC_SEMAPHORES +_POSIX_SHARED_MEMORY_OBJECTS@_SC_SHARED_MEMORY_OBJECTS +_POSIX_SHELL@_SC_SHELL +_POSIX_SPAWN@_SC_SPAWN +_POSIX_SPIN_LOCKS@_SC_SPIN_LOCKS +_POSIX_SPORADIC_SERVER@_SC_SPORADIC_SERVER +_POSIX_SS_REPL_MAX@_SC_SS_REPL_MAX +_POSIX_SYNCHRONIZED_IO@_SC_SYNCHRONIZED_IO +_POSIX_THREAD_ATTR_STACKADDR@_SC_THREAD_ATTR_STACKADDR +_POSIX_THREAD_ATTR_STACKSIZE@_SC_THREAD_ATTR_STACKSIZE +_POSIX_THREAD_CPUTIME@_SC_THREAD_CPUTIME +_POSIX_THREAD_PRIO_INHERIT@_SC_THREAD_PRIO_INHERIT +_POSIX_THREAD_PRIO_PROTECT@_SC_THREAD_PRIO_PROTECT +_POSIX_THREAD_PRIORITY_SCHEDULING@_SC_THREAD_PRIORITY_SCHEDULING +_POSIX_THREAD_PROCESS_SHARED@_SC_THREAD_PROCESS_SHARED +_POSIX_THREAD_ROBUST_PRIO_INHERIT@_SC_THREAD_ROBUST_PRIO_INHERIT +_POSIX_THREAD_ROBUST_PRIO_PROTECT@_SC_THREAD_ROBUST_PRIO_PROTECT +_POSIX_THREAD_SAFE_FUNCTIONS@_SC_THREAD_SAFE_FUNCTIONS +_POSIX_THREAD_SPORADIC_SERVER@_SC_THREAD_SPORADIC_SERVER +_POSIX_THREADS@_SC_THREADS +_POSIX_TIMEOUTS@_SC_TIMEOUTS +.TE +.TS +box center tab(@); +cB | cB +lw(2.85i)1e | le. +Variable@Value of Name +_ +_POSIX_TIMERS@_SC_TIMERS +_POSIX_TRACE@_SC_TRACE +_POSIX_TRACE_EVENT_FILTER@_SC_TRACE_EVENT_FILTER +_POSIX_TRACE_EVENT_NAME_MAX@_SC_TRACE_EVENT_NAME_MAX +_POSIX_TRACE_INHERIT@_SC_TRACE_INHERIT +_POSIX_TRACE_LOG@_SC_TRACE_LOG +_POSIX_TRACE_NAME_MAX@_SC_TRACE_NAME_MAX +_POSIX_TRACE_SYS_MAX@_SC_TRACE_SYS_MAX +_POSIX_TRACE_USER_EVENT_MAX@_SC_TRACE_USER_EVENT_MAX +_POSIX_TYPED_MEMORY_OBJECTS@_SC_TYPED_MEMORY_OBJECTS +_POSIX_VERSION@_SC_VERSION +_POSIX_V7_ILP32_OFF32@_SC_V7_ILP32_OFF32 +_POSIX_V7_ILP32_OFFBIG@_SC_V7_ILP32_OFFBIG +_POSIX_V7_LP64_OFF64@_SC_V7_LP64_OFF64 +_POSIX_V7_LPBIG_OFFBIG@_SC_V7_LPBIG_OFFBIG +_POSIX_V6_ILP32_OFF32@_SC_V6_ILP32_OFF32 +_POSIX_V6_ILP32_OFFBIG@_SC_V6_ILP32_OFFBIG +_POSIX_V6_LP64_OFF64@_SC_V6_LP64_OFF64 +_POSIX_V6_LPBIG_OFFBIG@_SC_V6_LPBIG_OFFBIG +_POSIX2_C_BIND@_SC_2_C_BIND +_POSIX2_C_DEV@_SC_2_C_DEV +_POSIX2_CHAR_TERM@_SC_2_CHAR_TERM +_POSIX2_FORT_DEV@_SC_2_FORT_DEV +_POSIX2_FORT_RUN@_SC_2_FORT_RUN +_POSIX2_LOCALEDEF@_SC_2_LOCALEDEF +_POSIX2_PBS@_SC_2_PBS +_POSIX2_PBS_ACCOUNTING@_SC_2_PBS_ACCOUNTING +_POSIX2_PBS_CHECKPOINT@_SC_2_PBS_CHECKPOINT +_POSIX2_PBS_LOCATE@_SC_2_PBS_LOCATE +_POSIX2_PBS_MESSAGE@_SC_2_PBS_MESSAGE +_POSIX2_PBS_TRACK@_SC_2_PBS_TRACK +_POSIX2_SW_DEV@_SC_2_SW_DEV +_POSIX2_UPE@_SC_2_UPE +_POSIX2_VERSION@_SC_2_VERSION +_XOPEN_CRYPT@_SC_XOPEN_CRYPT +_XOPEN_ENH_I18N@_SC_XOPEN_ENH_I18N +_XOPEN_REALTIME@_SC_XOPEN_REALTIME +_XOPEN_REALTIME_THREADS@_SC_XOPEN_REALTIME_THREADS +_XOPEN_SHM@_SC_XOPEN_SHM +_XOPEN_STREAMS@_SC_XOPEN_STREAMS +_XOPEN_UNIX@_SC_XOPEN_UNIX +_XOPEN_UUCP@_SC_XOPEN_UUCP +_XOPEN_VERSION@_SC_XOPEN_VERSION +.TE +.ad b +.SH "RETURN VALUE" +If +.IR name +is an invalid value, +\fIsysconf\fR() +shall return \-1 and set +.IR errno +to indicate the error. If the variable corresponding to +.IR name +is described in +.IR +as a maximum or minimum value and the variable has no limit, +\fIsysconf\fR() +shall return \-1 without changing the value of +.IR errno . +Note that indefinite limits do not imply infinite limits; see +.IR . +.P +Otherwise, +\fIsysconf\fR() +shall return the current variable value on the system. The value +returned shall not be more restrictive than the corresponding value +described to the application when it was compiled with the +implementation's +.IR +or +.IR . +The value shall not change during the lifetime of the calling process, +except that \fIsysconf\fP(_SC_OPEN_MAX) may return different values +before and after a call to +\fIsetrlimit\fR() +which changes the RLIMIT_NOFILE soft limit. +.P +If the variable corresponding to +.IR name +is dependent on an unsupported option, the results are unspecified. +.SH ERRORS +The +\fIsysconf\fR() +function shall fail if: +.TP +.BR EINVAL +The value of the +.IR name +argument is invalid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +As \-1 is a permissible return value in a successful situation, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIsysconf\fR(), +and, if it returns \-1, check to see if +.IR errno +is non-zero. +.P +Application developers should check whether an option, such as +_POSIX_TRACE, is supported prior to obtaining and using values for +related variables, such as _POSIX_TRACE_NAME_MAX. +.SH RATIONALE +This functionality was added in response to requirements of application +developers and of system vendors who deal with many international +system configurations. It is closely related to +\fIpathconf\fR() +and +\fIfpathconf\fR(). +.P +Although a conforming application can run on all systems by never +demanding more resources than the minimum values published in this volume of POSIX.1\(hy2017, it +is useful for that application to be able to use the actual value for +the quantity of a resource available on any given system. To do this, +the application makes use of the value of a symbolic constant in +.IR +or +.IR . +.P +However, once compiled, the application must still be able to cope if +the amount of resource available is increased. To that end, an +application may need a means of determining the quantity of a resource, +or the presence of an option, at execution time. +.P +Two examples are offered: +.IP " 1." 4 +Applications may wish to act differently on systems with or without job +control. +Applications vendors who wish to distribute only a single binary +package to all instances of a computer architecture would be forced to +assume job control is never available if it were to rely solely on the +.IR +value published in this volume of POSIX.1\(hy2017. +.IP " 2." 4 +International applications vendors occasionally require knowledge of +the number of clock ticks per second. +Without these facilities, they would be required to either distribute +their applications partially in source form or to have 50 Hz and 60 Hz +versions for the various countries in which they operate. +.P +It is the knowledge that many applications are actually distributed +widely in executable form that leads to this facility. If limited to +the most restrictive values in the headers, such applications would +have to be prepared to accept the most limited environments offered by +the smallest microcomputers. Although this is entirely portable, there +was a consensus that they should be able to take advantage of the +facilities offered by large systems, without the restrictions +associated with source and object distributions. +.P +During the discussions of this feature, it was pointed out that it is +almost always possible for an application to discern what a value might +be at runtime by suitably testing the various functions themselves. +And, in any event, it could always be written to adequately deal with +error returns from the various functions. In the end, it was felt that +this imposed an unreasonable level of complication and sophistication +on the application developer. +.P +This runtime facility is not meant to provide ever-changing values +that applications have to check multiple times. The values are seen as +changing no more frequently than once per system initialization, such +as by a system administrator or operator with an automatic +configuration program. This volume of POSIX.1\(hy2017 specifies that they shall not change +within the lifetime of the process. +.P +Some values apply to the system overall and others vary at the file +system or directory level. The latter are described in +.IR "\fIfpathconf\fR\^(\|)". +.P +Note that all values returned must be expressible as integers. String +values were considered, but the additional flexibility of this approach +was rejected due to its added complexity of implementation and use. +.P +Some values, such as +{PATH_MAX}, +are sometimes so large that they must not be used to, say, allocate +arrays. The +\fIsysconf\fR() +function returns a negative value to show that this symbolic constant +is not even defined in this case. +.P +Similar to +\fIpathconf\fR(), +this permits the implementation not to have a limit. When one resource +is infinite, returning an error indicating that some other resource +limit has been reached is conforming behavior. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIconfstr\fR\^(\|)", +.IR "\fIfpathconf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIgetconf\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/syslog.3p b/upstream/archlinux/man3p/syslog.3p new file mode 100644 index 00000000..c1092147 --- /dev/null +++ b/upstream/archlinux/man3p/syslog.3p @@ -0,0 +1,40 @@ +'\" et +.TH SYSLOG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +syslog +\(em log a message +.SH SYNOPSIS +.LP +.nf +#include +.P +void syslog(int \fIpriority\fP, const char *\fImessage\fP, ... /* \fIargument\fP */); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIcloselog\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/system.3p b/upstream/archlinux/man3p/system.3p new file mode 100644 index 00000000..d24bc896 --- /dev/null +++ b/upstream/archlinux/man3p/system.3p @@ -0,0 +1,476 @@ +'\" et +.TH SYSTEM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +system +\(em issue a command +.SH SYNOPSIS +.LP +.nf +#include +.P +int system(const char *\fIcommand\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR command +is a null pointer, the +\fIsystem\fR() +function shall determine whether the host environment has a command +processor. If +.IR command +is not a null pointer, the +\fIsystem\fR() +function shall pass the string pointed to by +.IR command +to that command processor to be executed in an implementation-defined +manner; this might then cause the program calling +\fIsystem\fR() +to behave in a non-conforming manner or to terminate. +.P +The +\fIsystem\fR() +function shall behave as if a child process were created using +\fIfork\fR(), +and the child process invoked the +.IR sh +utility using +\fIexecl\fR() +as follows: +.sp +.RS 4 +.nf + +execl(<\fIshell path\fP>, "sh", "-c", \fIcommand\fP, (char *)0); +.fi +.P +.RE +.P +where <\fIshell path\fP> is an unspecified pathname for the +.IR sh +utility. It is unspecified whether the handlers registered with +\fIpthread_atfork\fR() +are called as part of the creation of the child process. +.P +The +\fIsystem\fR() +function shall ignore the SIGINT and SIGQUIT signals, and shall +block the SIGCHLD +signal, while waiting for the command to terminate. If this might +cause the application to miss a signal that would have killed it, then +the application should examine the return value from +\fIsystem\fR() +and take whatever action is appropriate to the application if the +command terminated due to receipt of a signal. +.P +The +\fIsystem\fR() +function shall not affect the termination status of any child of the +calling processes other than the process or processes it itself +creates. +.P +The +\fIsystem\fR() +function shall not return until the child process has terminated. +.P +The +\fIsystem\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +If +.IR command +is a null pointer, +\fIsystem\fR() +shall return non-zero to indicate that a command processor is +available, or zero if none is available. +The +\fIsystem\fR() +function shall always return non-zero when +.IR command +is NULL. +.P +If +.IR command +is not a null pointer, +\fIsystem\fR() +shall return the termination status of the command language interpreter +in the format specified by +\fIwaitpid\fR(). +The termination status shall be as defined for the +.IR sh +utility; otherwise, the termination status is unspecified. If some +error prevents the command language interpreter from executing after +the child process is created, the return value from +\fIsystem\fR() +shall be as if the command language interpreter had terminated using +.IR exit (127) +or +.IR _exit (127). +If a child process cannot be created, or if the termination status for +the command language interpreter cannot be obtained, +\fIsystem\fR() +shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIsystem\fR() +function may set +.IR errno +values as described by +.IR "\fIfork\fR\^(\|)". +.br +.P +In addition, +\fIsystem\fR() +may fail if: +.TP +.BR ECHILD +The status of the child process created by +\fIsystem\fR() +is no longer available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the return value of +\fIsystem\fR() +is not \-1, its value can be decoded through the use of the macros +described in +.IR . +For convenience, these macros are also provided in +.IR . +.P +Note that, while +\fIsystem\fR() +must ignore SIGINT and SIGQUIT and block SIGCHLD while waiting for the +child to terminate, the handling of signals in the executed command is +as specified by +\fIfork\fR() +and +.IR exec . +For example, if SIGINT is being caught or is set to SIG_DFL when +\fIsystem\fR() +is called, then the child is started with SIGINT handling set to +SIG_DFL. +.P +Ignoring SIGINT and SIGQUIT in the parent process prevents coordination +problems (two processes reading from the same terminal, for example) +when the executed command ignores or catches one of the signals. It is +also usually the correct action when the user has given a command to +the application to be executed synchronously (as in the +.BR '!' +command in many interactive applications). In either case, the signal +should be delivered only to the child process, not to the application +itself. There is one situation where ignoring the signals might have +less than the desired effect. This is when the application uses +\fIsystem\fR() +to perform some task invisible to the user. If the user typed the +interrupt character (\c +.BR \(dq\(haC\(dq , +for example) while +\fIsystem\fR() +is being used in this way, one would expect the application to be +killed, but only the executed command is killed. Applications that use +\fIsystem\fR() +in this way should carefully check the return status from +\fIsystem\fR() +to see if the executed command was successful, and should take +appropriate action when the command fails. +.P +Blocking SIGCHLD while waiting for the child to terminate prevents the +application from catching the signal and obtaining status from +\fIsystem\fR()'s +child process before +\fIsystem\fR() +can get the status itself. +.P +The context in which the utility is ultimately executed may differ from +that in which +\fIsystem\fR() +was called. For example, file descriptors that have the FD_CLOEXEC +flag set are closed, and the process ID and parent process ID are +different. Also, if the executed utility changes its environment +variables or its current working directory, that change is not +reflected in the caller's context. +.P +There is no defined way for an application to find the specific path +for the shell. However, +\fIconfstr\fR() +can provide a value for +.IR PATH +that is guaranteed to find the +.IR sh +utility. +.P +Using the +\fIsystem\fR() +function in more than one thread in a process or when the SIGCHLD +signal is being manipulated by more than one thread in a process may +produce unexpected results. +.SH RATIONALE +The +\fIsystem\fR() +function should not be used by programs that have set user (or group) +ID privileges. The +\fIfork\fR() +and +.IR exec +family of functions (except +\fIexeclp\fR() +and +\fIexecvp\fR()), +should be used instead. This prevents any unforeseen manipulation of +the environment of the user that could cause execution of commands not +anticipated by the calling program. +.P +There are three levels of specification for the +\fIsystem\fR() +function. The ISO\ C standard gives the most basic. It requires that the function +exists, and defines a way for an application to query whether a command +language interpreter exists. It says nothing about the command language +or the environment in which the command is interpreted. +.P +POSIX.1\(hy2008 places additional restrictions on +\fIsystem\fR(). +It requires that if there is a command language interpreter, the +environment must be as specified by +\fIfork\fR() +and +.IR exec . +This ensures, for example, that close-on-\c +.IR exec +works, that file locks are not inherited, and that the process ID is +different. It also specifies the return value from +\fIsystem\fR() +when the command line can be run, thus giving the application some +information about the command's completion status. +.P +Finally, POSIX.1\(hy2008 requires the command to be interpreted as in the shell +command language defined in the Shell and Utilities volume of POSIX.1\(hy2017. +.P +Note that, +.IR system (NULL) +is required to return non-zero, indicating that there is a command +language interpreter. At first glance, this would seem to conflict with +the ISO\ C standard which allows +.IR system (NULL) +to return zero. There is no conflict, however. A system must have a +command language interpreter, and is non-conforming if none is present. +It is therefore permissible for the +\fIsystem\fR() +function on such a system to implement the behavior specified by the +ISO\ C standard as long as it is understood that the implementation does not +conform to POSIX.1\(hy2008 if +.IR system (NULL) +returns zero. +.P +It was explicitly decided that when +.IR command +is NULL, +\fIsystem\fR() +should not be required to check to make sure that the command language +interpreter actually exists with the correct mode, that there are +enough processes to execute it, and so on. The call +.IR system (NULL) +could, theoretically, check for such problems as too many existing +child processes, and return zero. However, it would be inappropriate to +return zero due to such a (presumably) transient condition. If some +condition exists that is not under the control of this application and +that would cause any +\fIsystem\fR() +call to fail, that system has been rendered non-conforming. +.P +Early drafts required, or allowed, +\fIsystem\fR() +to return with +.IR errno +set to +.BR [EINTR] +if it was interrupted with a signal. This error return was removed, and +a requirement that +\fIsystem\fR() +not return until the child has terminated was added. This means that if +a +\fIwaitpid\fR() +call in +\fIsystem\fR() +exits with +.IR errno +set to +.BR [EINTR] , +\fIsystem\fR() +must reissue the +\fIwaitpid\fR(). +This change was made for two reasons: +.IP " 1." 4 +There is no way for an application to clean up if +\fIsystem\fR() +returns +.BR [EINTR] , +short of calling +\fIwait\fR(), +and that could have the undesirable effect of returning the status of +children other than the one started by +\fIsystem\fR(). +.IP " 2." 4 +While it might require a change in some historical implementations, +those implementations already have to be changed because they use +\fIwait\fR() +instead of +\fIwaitpid\fR(). +.P +Note that if the application is catching SIGCHLD signals, it will +receive such a signal before a successful +\fIsystem\fR() +call returns. +.P +To conform to POSIX.1\(hy2008, +\fIsystem\fR() +must use +\fIwaitpid\fR(), +or some similar function, instead of +\fIwait\fR(). +.P +The following code sample illustrates how +\fIsystem\fR() +might be implemented on an implementation conforming to POSIX.1\(hy2008. +.sp +.RS 4 +.nf + +#include +int system(const char *cmd) +{ + int stat; + pid_t pid; + struct sigaction sa, savintr, savequit; + sigset_t saveblock; + if (cmd == NULL) + return(1); + sa.sa_handler = SIG_IGN; + sigemptyset(&sa.sa_mask); + sa.sa_flags = 0; + sigemptyset(&savintr.sa_mask); + sigemptyset(&savequit.sa_mask); + sigaction(SIGINT, &sa, &savintr); + sigaction(SIGQUIT, &sa, &savequit); + sigaddset(&sa.sa_mask, SIGCHLD); + sigprocmask(SIG_BLOCK, &sa.sa_mask, &saveblock); + if ((pid = fork()) == 0) { + sigaction(SIGINT, &savintr, (struct sigaction *)0); + sigaction(SIGQUIT, &savequit, (struct sigaction *)0); + sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); + execl("/bin/sh", "sh", "-c", cmd, (char *)0); + _exit(127); + } + if (pid == -1) { + stat = -1; /* errno comes from fork() */ + } else { + while (waitpid(pid, &stat, 0) == -1) { + if (errno != EINTR){ + stat = -1; + break; + } + } + } + sigaction(SIGINT, &savintr, (struct sigaction *)0); + sigaction(SIGQUIT, &savequit, (struct sigaction *)0); + sigprocmask(SIG_SETMASK, &saveblock, (sigset_t *)0); + return(stat); +} +.fi +.P +.RE +.P +Note that, while a particular implementation of +\fIsystem\fR() +(such as the one above) can assume a particular path for the shell, +such a path is not necessarily valid on another system. The above +example is not portable, and is not intended to be. +.P +Note also that the above example implementation is not thread-safe. +Implementations can provide a thread-safe +\fIsystem\fR() +function, but doing so involves complications such as how to restore the +signal dispositions for SIGINT and SIGQUIT correctly if there are +overlapping calls, and how to deal with cancellation. The example +above would not restore the signal dispositions and would leak +a process ID if cancelled. This does not matter for a +non-thread-safe implementation since canceling a non-thread-safe +function results in undefined behavior (see +.IR "Section 2.9.5.2" ", " "Cancellation Points"). +To avoid leaking a process ID, a thread-safe implementation would need +to terminate the child process when acting on a cancellation. +.P +One reviewer suggested that an implementation of +\fIsystem\fR() +might want to use an environment variable such as +.IR SHELL +to determine which command interpreter to use. The supposed +implementation would use the default command interpreter if the one +specified by the environment variable was not available. This would +allow a user, when using an application that prompts for command lines +to be processed using +\fIsystem\fR(), +to specify a different command interpreter. Such an implementation is +discouraged. If the alternate command interpreter did not follow the +command line syntax specified in the Shell and Utilities volume of POSIX.1\(hy2017, then changing +.IR SHELL +would render +\fIsystem\fR() +non-conforming. This would affect applications that expected the +specified behavior from +\fIsystem\fR(), +and since the Shell and Utilities volume of POSIX.1\(hy2017 does not mention that +.IR SHELL +affects +\fIsystem\fR(), +the application would not know that it needed to unset +.IR SHELL . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.9.5.2" ", " "Cancellation Points", +.IR "\fIexec\fR\^", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIpthread_atfork\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "\fIsh\fR\^" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tan.3p b/upstream/archlinux/man3p/tan.3p new file mode 100644 index 00000000..40a38b86 --- /dev/null +++ b/upstream/archlinux/man3p/tan.3p @@ -0,0 +1,208 @@ +'\" et +.TH TAN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tan, +tanf, +tanl +\(em tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +double tan(double \fIx\fP); +float tanf(float \fIx\fP); +long double tanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the tangent of their argument +.IR x , +measured in radians. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the tangent of +.IR x . +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fItan\fR(), +\fItanf\fR(), +and +\fItanl\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fItan\fR(), +\fItanf\fR(), +and +\fItanl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.P +If +.IR x +is \(+-Inf, a domain error shall occur, and either a NaN (if +supported), or an implementation-defined value shall be returned. +.P +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be returned. +.P +If the correct value would cause overflow, a range error shall occur +and +\fItan\fR(), +\fItanf\fR(), +and +\fItanl\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is \(+-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The result overflows +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.br +.P +These functions may fail if: +.IP "Range\ Error" 12 +The result underflows, +or the value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Taking the Tangent of a 45-Degree Angle" +.sp +.RS 4 +.nf + +#include +\&... +double radians = 45.0 * M_PI / 180; +double result; +\&... +result = tan (radians); +.fi +.P +.RE +.SH "APPLICATION USAGE" +There are no known floating-point representations such that for a +normal argument, +.IR tan (\c +.IR x ) +is either overflow or underflow. +.P +These functions may lose accuracy when their argument is near a +multiple of \(*p/2 or is far from 0.0. +.P +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatan\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tanh.3p b/upstream/archlinux/man3p/tanh.3p new file mode 100644 index 00000000..892fd219 --- /dev/null +++ b/upstream/archlinux/man3p/tanh.3p @@ -0,0 +1,131 @@ +'\" et +.TH TANH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tanh, +tanhf, +tanhl +\(em hyperbolic tangent functions +.SH SYNOPSIS +.LP +.nf +#include +.P +double tanh(double \fIx\fP); +float tanhf(float \fIx\fP); +long double tanhl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute the hyperbolic tangent of their argument +.IR x . +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the hyperbolic +tangent of +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0, +.IR x +shall be returned. +.P +If +.IR x +is \(+-Inf, \(+-1 shall be returned. +.P +If +.IR x +is subnormal, a range error may occur +.br +and +.IR x +should be returned. +.P +If +.IR x +is not returned, +\fItanh\fR(), +\fItanhf\fR(), +and +\fItanhl\fR() +shall return an implementation-defined value no greater in magnitude +than DBL_MIN, FLT_MIN, and LDBL_MIN, respectively. +.SH ERRORS +These functions may fail if: +.IP "Range\ Error" 12 +The value of +.IR x +is subnormal. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIatanh\fR\^(\|)", +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fItan\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tanl.3p b/upstream/archlinux/man3p/tanl.3p new file mode 100644 index 00000000..a863623d --- /dev/null +++ b/upstream/archlinux/man3p/tanl.3p @@ -0,0 +1,40 @@ +'\" et +.TH TANL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tanl +\(em tangent function +.SH SYNOPSIS +.LP +.nf +#include +.P +long double tanl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItan\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcdrain.3p b/upstream/archlinux/man3p/tcdrain.3p new file mode 100644 index 00000000..d98a56fa --- /dev/null +++ b/upstream/archlinux/man3p/tcdrain.3p @@ -0,0 +1,99 @@ +'\" et +.TH TCDRAIN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcdrain +\(em wait for transmission of output +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcdrain(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fItcdrain\fR() +function shall block until all output written to the object referred +to by +.IR fildes +is transmitted. The +.IR fildes +argument is an open file descriptor associated with a terminal. +.P +Any attempts to use +\fItcdrain\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal, shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcdrain\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINTR +A signal interrupted +\fItcdrain\fR(). +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcflush\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcflow.3p b/upstream/archlinux/man3p/tcflow.3p new file mode 100644 index 00000000..c886702f --- /dev/null +++ b/upstream/archlinux/man3p/tcflow.3p @@ -0,0 +1,135 @@ +'\" et +.TH TCFLOW "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcflow +\(em suspend or restart the transmission or reception of data +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcflow(int \fIfildes\fP, int \fIaction\fP); +.fi +.SH DESCRIPTION +The +\fItcflow\fR() +function shall suspend or restart transmission or reception of data on +the object referred to by +.IR fildes , +depending on the value of +.IR action . +The +.IR fildes +argument is an open file descriptor associated with a terminal. +.IP " *" 4 +If +.IR action +is TCOOFF, output shall be suspended. +.IP " *" 4 +If +.IR action +is TCOON, suspended output shall be restarted. +.IP " *" 4 +If +.IR action +is TCIOFF and +.IR fildes +refers to a terminal device, the system shall transmit a STOP character, +which is intended to cause the terminal device to stop transmitting data +to the system. If +.IR fildes +is associated with a pseudo-terminal, the STOP character need not be +transmitted. +.IP " *" 4 +If +.IR action +is TCION and +.IR fildes +refers to a terminal device, the system shall transmit a START character, +which is intended to cause the terminal device to start transmitting +data to the system. If +.IR fildes +is associated with a pseudo-terminal, the START character need not be +transmitted. +.P +The default on the opening of a terminal file is that neither its input +nor its output are suspended. +.P +Attempts to use +\fItcflow\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal, shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcflow\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR action +argument is not a supported value. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcsendbreak\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcflush.3p b/upstream/archlinux/man3p/tcflush.3p new file mode 100644 index 00000000..8313141c --- /dev/null +++ b/upstream/archlinux/man3p/tcflush.3p @@ -0,0 +1,112 @@ +'\" et +.TH TCFLUSH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcflush +\(em flush non-transmitted output data, non-read input data, or both +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcflush(int \fIfildes\fP, int \fIqueue_selector\fP); +.fi +.SH DESCRIPTION +Upon successful completion, +\fItcflush\fR() +shall discard data written to the object referred to by +.IR fildes +(an open file descriptor associated with a terminal) but not +transmitted, or data received but not read, depending on the value of +.IR queue_selector : +.IP " *" 4 +If +.IR queue_selector +is TCIFLUSH, it shall flush data received but not read. +.IP " *" 4 +If +.IR queue_selector +is TCOFLUSH, it shall flush data written but not transmitted. +.IP " *" 4 +If +.IR queue_selector +is TCIOFLUSH, it shall flush both data received but not read and data +written but not transmitted. +.P +Attempts to use +\fItcflush\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcflush\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +The +.IR queue_selector +argument is not a supported value. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcdrain\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcgetattr.3p b/upstream/archlinux/man3p/tcgetattr.3p new file mode 100644 index 00000000..5f209fce --- /dev/null +++ b/upstream/archlinux/man3p/tcgetattr.3p @@ -0,0 +1,148 @@ +'\" et +.TH TCGETATTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcgetattr +\(em get the parameters associated with the terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcgetattr(int \fIfildes\fP, struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fItcgetattr\fR() +function shall get the parameters associated with the terminal referred +to by +.IR fildes +and store them in the +.BR termios +structure referenced by +.IR termios_p . +The +.IR fildes +argument is an open file descriptor associated with a terminal. +.P +The +.IR termios_p +argument is a pointer to a +.BR termios +structure. +.P +The +\fItcgetattr\fR() +operation is allowed from any process. +.P +If the terminal device supports different input and output baud rates, +the baud rates stored in the +.BR termios +structure returned by +\fItcgetattr\fR() +shall reflect the actual baud rates, even if they are equal. If +differing baud rates are not supported, the rate returned as the output +baud rate shall be the actual baud rate. If the terminal device does +not support split baud rates, the input baud rate stored in the +.BR termios +structure shall be the output rate (as one of the symbolic values). +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcgetattr\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Care must be taken when changing the terminal attributes. Applications +should always do a +\fItcgetattr\fR(), +save the +.BR termios +structure values returned, and then do a +\fItcsetattr\fR(), +changing only the necessary fields. The application should use the +values saved from the +\fItcgetattr\fR() +to reset the terminal state whenever it is done with the terminal. +This is necessary because terminal attributes apply to the underlying +port and not to each individual open instance; that is, all processes +that have used the terminal see the latest attribute changes. +.P +A program that uses these functions should be written to catch all +signals and take other appropriate actions to ensure that when the +program terminates, whether planned or not, the terminal device's state +is restored to its original state. +.P +Existing practice dealing with error returns when only part of a +request can be honored is based on calls to the +\fIioctl\fR() +function. In historical BSD and System V implementations, +the corresponding +\fIioctl\fR() +returns zero if the requested actions were semantically correct, even +if some of the requested changes could not be made. Many existing +applications assume this behavior and would no longer work correctly if +the return value were changed from zero to \-1 in this case. +.P +Note that either specification has a problem. When zero is returned, +it implies everything succeeded even if some of the changes were not +made. When \-1 is returned, it implies everything failed even though +some of the changes were made. +.P +Applications that need all of the requested changes made to work +properly should follow +\fItcsetattr\fR() +with a call to +\fItcgetattr\fR() +and compare the appropriate field values. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcsetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcgetpgrp.3p b/upstream/archlinux/man3p/tcgetpgrp.3p new file mode 100644 index 00000000..1bc04373 --- /dev/null +++ b/upstream/archlinux/man3p/tcgetpgrp.3p @@ -0,0 +1,92 @@ +'\" et +.TH TCGETPGRP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcgetpgrp +\(em get the foreground process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t tcgetpgrp(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fItcgetpgrp\fR() +function shall return the value of the process group ID of the +foreground process group associated with the terminal. +.P +If there is no foreground process group, +\fItcgetpgrp\fR() +shall return a value greater than 1 that does not match the process +group ID of any existing process group. +.P +The +\fItcgetpgrp\fR() +function is allowed from a process that is a member of a background +process group; however, the information may be subsequently changed by +a process that is a member of a foreground process group. +.SH "RETURN VALUE" +Upon successful completion, +\fItcgetpgrp\fR() +shall return the value of the process group ID of the foreground +process associated with the terminal. Otherwise, \-1 shall be +returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcgetpgrp\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetsid\fR\^(\|)", +.IR "\fIsetpgid\fR\^(\|)", +.IR "\fItcsetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcgetsid.3p b/upstream/archlinux/man3p/tcgetsid.3p new file mode 100644 index 00000000..e36c2b4c --- /dev/null +++ b/upstream/archlinux/man3p/tcgetsid.3p @@ -0,0 +1,78 @@ +'\" et +.TH TCGETSID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcgetsid +\(em get the process group ID for the session leader for the +controlling terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t tcgetsid(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fItcgetsid\fR() +function shall obtain the process group ID of the session for which the +terminal specified by +.IR fildes +is the controlling terminal. +.SH "RETURN VALUE" +Upon successful completion, +\fItcgetsid\fR() +shall return the process group ID of the session associated with the +terminal. Otherwise, a value of \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcgetsid\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcsendbreak.3p b/upstream/archlinux/man3p/tcsendbreak.3p new file mode 100644 index 00000000..c61032bc --- /dev/null +++ b/upstream/archlinux/man3p/tcsendbreak.3p @@ -0,0 +1,105 @@ +'\" et +.TH TCSENDBREAK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcsendbreak +\(em send a break for a specific duration +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcsendbreak(int \fIfildes\fP, int \fIduration\fP); +.fi +.SH DESCRIPTION +If the terminal is using asynchronous serial data transmission, +\fItcsendbreak\fR() +shall cause transmission of a continuous stream of zero-valued bits for +a specific duration. If +.IR duration +is 0, it shall cause transmission of zero-valued bits for at least 0.25 +seconds, and not more than 0.5 seconds. If +.IR duration +is not 0, it shall send zero-valued bits for an +implementation-defined period of time. +.P +The +.IR fildes +argument is an open file descriptor associated with a terminal. +.P +If the terminal is not using asynchronous serial data transmission, it +is implementation-defined whether +\fItcsendbreak\fR() +sends data to generate a break condition or returns without taking any +action. +.P +Attempts to use +\fItcsendbreak\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal shall cause the process group +to be sent a SIGTTOU signal. +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the process shall be allowed to perform the +operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 shall +be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcsendbreak\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcsetattr.3p b/upstream/archlinux/man3p/tcsetattr.3p new file mode 100644 index 00000000..467d5fe6 --- /dev/null +++ b/upstream/archlinux/man3p/tcsetattr.3p @@ -0,0 +1,242 @@ +'\" et +.TH TCSETATTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcsetattr +\(em set the parameters associated with the terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcsetattr(int \fIfildes\fP, int \fIoptional_actions\fP, + const struct termios *\fItermios_p\fP); +.fi +.SH DESCRIPTION +The +\fItcsetattr\fR() +function shall set the parameters associated with the terminal referred +to by the open file descriptor +.IR fildes +(an open file descriptor associated with a terminal) from the +.BR termios +structure referenced by +.IR termios_p +as follows: +.IP " *" 4 +If +.IR optional_actions +is TCSANOW, the change shall occur immediately. +.IP " *" 4 +If +.IR optional_actions +is TCSADRAIN, the change shall occur after all output written to +.IR fildes +is transmitted. This function should be used when changing parameters +that affect output. +.IP " *" 4 +If +.IR optional_actions +is TCSAFLUSH, the change shall occur after all output written to +.IR fildes +is transmitted, and all input so far received but not read shall be +discarded before the change is made. +.P +If the output baud rate stored in the +.BR termios +structure pointed to by +.IR termios_p +is the zero baud rate, B0, the modem control lines shall no longer +be asserted. Normally, this shall disconnect the line. +.P +If the input baud rate stored in the +.BR termios +structure pointed to by +.IR termios_p +is 0, the input baud rate given to the hardware is the same as the +output baud rate stored in the +.BR termios +structure. +.P +The +\fItcsetattr\fR() +function shall return successfully if it was able to perform any of the +requested actions, even if some of the requested actions could not be +performed. It shall set all the attributes that the implementation +supports as requested and leave all the attributes not supported by +the implementation unchanged. If no part of the request can be honored, +it shall return \-1 and set +.IR errno +to +.BR [EINVAL] . +If the input and output baud rates differ and are a combination that is +not supported, neither baud rate shall be changed. A subsequent call to +\fItcgetattr\fR() +shall return the actual state of the terminal device (reflecting both +the changes made and not made in the previous +\fItcsetattr\fR() +call). The +\fItcsetattr\fR() +function shall not change the values found in the +.BR termios +structure under any circumstances. +.P +The effect of +\fItcsetattr\fR() +is undefined if the value of the +.BR termios +structure pointed to by +.IR termios_p +was not derived from the result of a call to +\fItcgetattr\fR() +on +.IR fildes ; +an application should modify only fields and flags defined by this volume of POSIX.1\(hy2017 +between the call to +\fItcgetattr\fR() +and +\fItcsetattr\fR(), +leaving all other fields and flags unmodified. +.P +No actions defined by this volume of POSIX.1\(hy2017, other than a call to +\fItcsetattr\fR(), +a close of the last file descriptor in the system associated with this +terminal device, or an open of the first file descriptor in the system +associated with this terminal device (using the O_TTY_INIT flag if it +is non-zero and the device is not a pseudo-terminal), shall cause any +of the terminal attributes defined by this volume of POSIX.1\(hy2017 to change. +.P +If +\fItcsetattr\fR() +is called from a process which is a member of a background process +group on a +.IR fildes +associated with its controlling terminal: +.IP " *" 4 +If the calling thread is blocking SIGTTOU signals or the process is +ignoring SIGTTOU signals, the operation completes normally and no signal +is sent. +.IP " *" 4 +Otherwise, a SIGTTOU signal shall be sent to the process group. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, +\-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcsetattr\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINTR +A signal interrupted +\fItcsetattr\fR(). +.TP +.BR EINVAL +The +.IR optional_actions +argument is not a supported value, or an attempt was made to change an +attribute represented in the +.BR termios +structure to an unsupported value. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The file associated with +.IR fildes +is not a terminal. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If trying to change baud rates, applications should call +\fItcsetattr\fR() +then call +\fItcgetattr\fR() +in order to determine what baud rates were actually selected. +.P +In general, there are two reasons for an application to change the +parameters associated with a terminal device: +.IP " 1." 4 +The device already has working parameter settings but the application +needs a different behavior, such as non-canonical mode instead of +canonical mode. The application sets (or clears) only a few flags or +.IR c_cc [\^] +values. Typically, the terminal device in this case is either the +controlling terminal for the process or a pseudo-terminal. +.IP " 2." 4 +The device is a modem or similar piece of equipment connected by a serial +line, and it was not open before the application opened it. In this case, +the application needs to initialize all of the parameter settings ``from +scratch''. However, since the +.BR termios +structure may include both standard and non-standard parameters, the +application cannot just initialize the whole structure in an arbitrary +way (e.g., using +\fImemset\fR()) +as this may cause some of the non-standard parameters to be set +incorrectly, resulting in non-conforming behavior of the terminal +device. Conversely, the application cannot just set the standard +parameters, assuming that the non-standard parameters will already have +suitable values, as the device might previously have been used with +non-conforming parameter settings (and some implementations retain the +settings from one use to the next). The solution is to open the terminal +device using the O_TTY_INIT flag to initialize the terminal device to +have conforming parameter settings, obtain those settings using +\fItcgetattr\fR(), +and then set all of the standard parameters to the desired settings. +.SH RATIONALE +The +\fItcsetattr\fR() +function can be interrupted in the following situations: +.IP " *" 4 +It is interrupted while waiting for output to drain. +.IP " *" 4 +It is called from a process in a background process group and SIGTTOU +is caught. +.P +See also the RATIONALE section in +.IR "\fItcgetattr\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +Using an input baud rate of 0 to set the input rate equal to the output +rate may not necessarily be supported in a future version of this volume of POSIX.1\(hy2017. +.SH "SEE ALSO" +.IR "\fIcfgetispeed\fR\^(\|)", +.IR "\fItcgetattr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 11" ", " "General Terminal Interface", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tcsetpgrp.3p b/upstream/archlinux/man3p/tcsetpgrp.3p new file mode 100644 index 00000000..0e77f0ea --- /dev/null +++ b/upstream/archlinux/man3p/tcsetpgrp.3p @@ -0,0 +1,111 @@ +'\" et +.TH TCSETPGRP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tcsetpgrp +\(em set the foreground process group ID +.SH SYNOPSIS +.LP +.nf +#include +.P +int tcsetpgrp(int \fIfildes\fP, pid_t \fIpgid_id\fP); +.fi +.SH DESCRIPTION +If the process has a controlling terminal, +\fItcsetpgrp\fR() +shall set the foreground process group ID associated with the terminal +to +.IR pgid_id . +The application shall ensure that the file associated with +.IR fildes +is the controlling terminal of the calling process and the controlling +terminal is currently associated with the session of the calling +process. The application shall ensure that the value of +.IR pgid_id +matches a process group ID of a process in the same session as the +calling process. +.P +Attempts to use +\fItcsetpgrp\fR() +from a process which is a member of a background process group on a +.IR fildes +associated with its controlling terminal shall cause the process group +to be sent a SIGTTOU signal. If the calling thread is blocking SIGTTOU +signals or the process is ignoring SIGTTOU signals, the process shall +be allowed to perform the operation, and no signal is sent. +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItcsetpgrp\fR() +function shall fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR EINVAL +This implementation does not support the value in the +.IR pgid_id +argument. +.TP +.BR EIO +The process group of the writing process is orphaned, the calling thread +is not blocking SIGTTOU, and the process is not ignoring SIGTTOU. +.TP +.BR ENOTTY +The calling process does not have a controlling terminal, or the file +is not the controlling terminal, or the controlling terminal is no +longer associated with the session of the calling process. +.TP +.BR EPERM +The value of +.IR pgid_id +is a value supported by the implementation, but does not match the +process group ID of a process in the same session as the calling +process. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItcgetpgrp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tdelete.3p b/upstream/archlinux/man3p/tdelete.3p new file mode 100644 index 00000000..d1fbd939 --- /dev/null +++ b/upstream/archlinux/man3p/tdelete.3p @@ -0,0 +1,357 @@ +'\" et +.TH TDELETE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tdelete, +tfind, +tsearch, +twalk +\(em manage a binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void *tdelete(const void *restrict \fIkey\fP, void **restrict \fIrootp\fP, + int(*\fIcompar\fP)(const void *, const void *)); +void *tfind(const void *\fIkey\fP, void *const *\fIrootp\fP, + int(*\fIcompar\fP)(const void *, const void *)); +void *tsearch(const void *\fIkey\fP, void **\fIrootp\fP, + int (*\fIcompar\fP)(const void *, const void *)); +void twalk(const void *\fIroot\fP, + void (*\fIaction\fP)(const void *, VISIT, int)); +.fi +.SH DESCRIPTION +The +\fItdelete\fR(), +\fItfind\fR(), +\fItsearch\fR(), +and +\fItwalk\fR() +functions manipulate binary search trees. Comparisons are made with a +user-supplied routine, the address of which is passed as the +.IR compar +argument. This routine is called with two arguments, which are the +pointers to the elements being compared. The application shall ensure +that the user-supplied routine returns an integer less than, equal to, +or greater than 0, according to whether the first argument is to be +considered less than, equal to, or greater than the second argument. +The comparison function need not compare every byte, so arbitrary data +may be contained in the elements in addition to the values being +compared. +.P +The +\fItsearch\fR() +function shall build and access the tree. The +.IR key +argument is a pointer to an element to be accessed or stored. If there +is a node in the tree whose element is equal to the value pointed to by +.IR key , +a pointer to this found node shall be returned. Otherwise, the value +pointed to by +.IR key +shall be inserted (that is, a new node is created and the value of +.IR key +is copied to this node), and a pointer to this node returned. Only +pointers are copied, so the application shall ensure that the calling +routine stores the data. The +.IR rootp +argument points to a variable that points to the root node of the +tree. A null pointer value for the variable pointed to by +.IR rootp +denotes an empty tree; in this case, the variable shall be set to point +to the node which shall be at the root of the new tree. +.P +Like +\fItsearch\fR(), +\fItfind\fR() +shall search for a node in the tree, returning a pointer to it if found. +However, if it is not found, +\fItfind\fR() +shall return a null pointer. The arguments for +\fItfind\fR() +are the same as for +\fItsearch\fR(). +.P +The +\fItdelete\fR() +function shall delete a node from a binary search tree. The arguments +are the same as for +\fItsearch\fR(). +The variable pointed to by +.IR rootp +shall be changed if the deleted node was the root of the tree. +If the deleted node was the root of the tree and had no children, the +variable pointed to by +.IR rootp +shall be set to a null pointer. The +\fItdelete\fR() +function shall return a pointer to the parent of the deleted node, or +an unspecified non-null pointer if the deleted node was the root node, +or a null pointer if the node is not found. +.P +If +\fItsearch\fR() +adds an element to a tree, or +\fItdelete\fR() +successfully deletes an element from a tree, the concurrent use of +that tree in another thread, or use of pointers produced by a previous +call to +\fItfind\fR() +or +\fItsearch\fR(), +produces undefined results. +.P +The +\fItwalk\fR() +function shall traverse a binary search tree. The +.IR root +argument is a pointer to the root node of the tree to be traversed. +(Any node in a tree may be used as the root for a walk below that +node.) The argument +.IR action +is the name of a routine to be invoked at each node. This routine is, +in turn, called with three arguments. The first argument shall be the +address of the node being visited. The structure pointed to by this +argument is unspecified and shall not be modified by the application, +but it shall be possible to cast a pointer-to-node into a +pointer-to-pointer-to-element to access the element stored in the node. +The second argument shall be a value from an enumeration data type: +.sp +.RS 4 +.nf + +typedef enum { preorder, postorder, endorder, leaf } VISIT; +.fi +.P +.RE +.P +(defined in +.IR ), +depending on whether this is the first, second, or third time that the +node is visited (during a depth-first, left-to-right traversal of the +tree), or whether the node is a leaf. The third argument shall be +the level of the node in the tree, with the root being level 0. +.P +If the calling function alters the pointer to the root, the result is +undefined. +.P +If the functions pointed to by +.IR action +or +.IR compar +(for any of these binary search functions) change the tree, the results +are undefined. +.P +These functions are thread-safe only as long as multiple threads +do not access the same tree. +.SH "RETURN VALUE" +If the node is found, both +\fItsearch\fR() +and +\fItfind\fR() +shall return a pointer to it. If not, +\fItfind\fR() +shall return a null pointer, and +\fItsearch\fR() +shall return a pointer to the inserted item. +.P +A null pointer shall be returned by +\fItsearch\fR() +if there is not enough space available to create a new node. +.P +A null pointer shall be returned by +\fItdelete\fR(), +\fItfind\fR(), +and +\fItsearch\fR() +if +.IR rootp +is a null pointer on entry. +.P +The +\fItdelete\fR() +function shall return a pointer to the parent of the deleted node, or +an unspecified non-null pointer if the deleted node was the root node, +or a null pointer if the node is not found. +.P +The +\fItwalk\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH "EXAMPLES" +The following code reads in strings and stores structures containing a +pointer to each string and a count of its length. It then walks the +tree, printing out the stored strings and their lengths in alphabetical +order. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +.P +struct element { /* Pointers to these are stored in the tree. */ + int count; + char string[]; +}; +.P +void *root = NULL; /* This points to the root. */ +.P +int main(void) +{ + char str[_POSIX2_LINE_MAX+1]; + int length = 0; + struct element *elementptr; + void *node; + void print_node(const void *, VISIT, int); + int node_compare(const void *, const void *), + delete_root(const void *, const void *); +.P + while (fgets(str, sizeof(str), stdin)) { + /* Set element. */ + length = strlen(str); + if (str[length-1] == \(aq\en\(aq) + str[--length] = \(aq\e0\(aq; + elementptr = malloc(sizeof(struct element) + length + 1); + strcpy(elementptr->string, str); + elementptr->count = 1; + /* Put element into the tree. */ + node = tsearch((void *)elementptr, &root, node_compare); + if (node == NULL) { + fprintf(stderr, + "tsearch: Not enough space available\en"); + exit(EXIT_FAILURE); + } + else if (*(struct element **)node != elementptr) { + /* A node containing the element already exists */ + (*(struct element **)node)->count++; + free(elementptr); + } + } + twalk(root, print_node); +.P + /* Delete all nodes in the tree */ + while (root != NULL) { + elementptr = *(struct element **)root; + printf("deleting node: string = %s, count = %d\en", + elementptr->string, + elementptr->count); + tdelete((void *)elementptr, &root, delete_root); + free(elementptr); + } +.P + return 0; +} +.P +/* + * This routine compares two nodes, based on an + * alphabetical ordering of the string field. + */ +int +node_compare(const void *node1, const void *node2) +{ + return strcmp(((const struct element *) node1)->string, + ((const struct element *) node2)->string); +} +.P +/* + * This comparison routine can be used with tdelete() + * when explicitly deleting a root node, as no comparison + * is necessary. + */ +int +delete_root(const void *node1, const void *node2) +{ + return 0; +} +.P +/* + * This routine prints out a node, the second time + * twalk encounters it or if it is a leaf. + */ +void +print_node(const void *ptr, VISIT order, int level) +{ + const struct element *p = *(const struct element **) ptr; +.P + if (order == postorder || order == leaf) { + (void) printf("string = %s, count = %d\en", + p->string, p->count); + } +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +The +.IR root +argument to +\fItwalk\fR() +is one level of indirection less than the +.IR rootp +arguments to +\fItdelete\fR() +and +\fItsearch\fR(). +.P +There are two nomenclatures used to refer to the order in which tree +nodes are visited. The +\fItwalk\fR() +function uses \fBpreorder\fP, \fBpostorder\fP, and \fBendorder\fP to +refer respectively to visiting a node before any of its children, after +its left child and before its right, and after both its children. The +alternative nomenclature uses \fBpreorder\fP, \fBinorder\fP, and +\fBpostorder\fP to refer to the same visits, which could result in some +confusion over the meaning of \fBpostorder\fP. +.P +Since the return value of +\fItdelete\fR() +is an unspecified non-null pointer in the case that the root of the tree +has been deleted, applications should only use the return value of +\fItdelete\fR() +as indication of success or failure and should not assume it can be +dereferenced. Some implementations in this case will return a pointer to +the new root of the tree (or to an empty tree if the deleted root node +was the only node in the tree); other implementations return arbitrary +non-null pointers. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIhcreate\fR\^(\|)", +.IR "\fIlsearch\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/telldir.3p b/upstream/archlinux/man3p/telldir.3p new file mode 100644 index 00000000..45a64a35 --- /dev/null +++ b/upstream/archlinux/man3p/telldir.3p @@ -0,0 +1,75 @@ +'\" et +.TH TELLDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +telldir +\(em current location of a named directory stream +.SH SYNOPSIS +.LP +.nf +#include +.P +long telldir(DIR *\fIdirp\fP); +.fi +.SH DESCRIPTION +The +\fItelldir\fR() +function shall obtain the current location associated with the +directory stream specified by +.IR dirp . +.P +If the most recent operation on the directory stream was a +\fIseekdir\fR(), +the directory position returned from the +\fItelldir\fR() +shall be the same as that supplied as a +.IR loc +argument for +\fIseekdir\fR(). +.SH "RETURN VALUE" +Upon successful completion, +\fItelldir\fR() +shall return the current location of the specified directory stream. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfdopendir\fR\^(\|)", +.IR "\fIreaddir\fR\^(\|)", +.IR "\fIseekdir\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tempnam.3p b/upstream/archlinux/man3p/tempnam.3p new file mode 100644 index 00000000..9478b90a --- /dev/null +++ b/upstream/archlinux/man3p/tempnam.3p @@ -0,0 +1,150 @@ +'\" et +.TH TEMPNAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tempnam +\(em create a name for a temporary file +.SH SYNOPSIS +.LP +.nf +#include +.P +char *tempnam(const char *\fIdir\fP, const char *\fIpfx\fP); +.fi +.SH DESCRIPTION +The +\fItempnam\fR() +function shall generate a pathname that may be used for a temporary +file. +.P +The +\fItempnam\fR() +function allows the user to control the choice of a directory. The +.IR dir +argument points to the name of the directory in which the file is to be +created. If +.IR dir +is a null pointer or points to a string which is not a name for an +appropriate directory, the path prefix defined as P_tmpdir in the +.IR +header shall be used. If that directory is not accessible, an +implementation-defined directory may be used. +.P +Many applications prefer their temporary files to have certain initial +letter sequences in their names. The +.IR pfx +argument should be used for this. This argument may be a null pointer +or point to a string of up to five bytes to be used as the beginning of +the filename. +.P +Some implementations of +\fItempnam\fR() +may use +\fItmpnam\fR() +internally. On such implementations, if called more than +{TMP_MAX} +times in a single process, the behavior is implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, +\fItempnam\fR() +shall allocate space for a string, put the generated pathname in that +space, and return a pointer to it. The pointer shall be suitable for +use in a subsequent call to +\fIfree\fR(). +Otherwise, it shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fItempnam\fR() +function shall fail if: +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pathname" +.P +The following example generates a pathname for a temporary file in +directory +.BR /tmp , +with the prefix +.IR file . +After the pathname has been created, the call to +\fIfree\fR() +deallocates the space used to store the pathname. +.sp +.RS 4 +.nf + +#include +#include +\&... +const char *directory = "/tmp"; +const char *fileprefix = "file"; +char *file; +.P +file = tempnam(directory, fileprefix); +free(file); +.fi +.P +.RE +.SH "APPLICATION USAGE" +This function only creates pathnames. It is the application's +responsibility to create and remove the files. Between the time a +pathname is created and the file is opened, it is possible for some +other process to create a file with the same name. Applications may +find +\fItmpfile\fR() +more useful. +.P +Applications should use the +\fItmpfile\fR(), +\fImkdtemp\fR(), +or +\fImkstemp\fR() +functions instead of the obsolescent +\fItempnam\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fItempnam\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfopen\fR\^(\|)", +.IR "\fIfree\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tfind.3p b/upstream/archlinux/man3p/tfind.3p new file mode 100644 index 00000000..5709cd5f --- /dev/null +++ b/upstream/archlinux/man3p/tfind.3p @@ -0,0 +1,41 @@ +'\" et +.TH TFIND "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tfind +\(em search binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void *tfind(const void *\fIkey\fP, void *const *\fIrootp\fP, + int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItdelete\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tgamma.3p b/upstream/archlinux/man3p/tgamma.3p new file mode 100644 index 00000000..19880a54 --- /dev/null +++ b/upstream/archlinux/man3p/tgamma.3p @@ -0,0 +1,251 @@ +'\" et +.TH TGAMMA "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.EQ +delim $$ +.EN +.SH NAME +tgamma, +tgammaf, +tgammal +\(em compute gamma(\|) function +.SH SYNOPSIS +.LP +.nf +#include +.P +double tgamma(double \fIx\fP); +float tgammaf(float \fIx\fP); +long double tgammal(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall compute $\(*G ( ^ x )$ +where $\(*G ( ^ x )$ is defined as +$int from 0 to inf e"^" " "{ - t } t"^" " "{ x - 1 } dt$. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the gamma of +.IR x . +.P +If +.IR x +is a negative integer, a +domain +error may occur and either a NaN (if supported) or an +implementation-defined value shall be returned. +On systems that support the IEC 60559 Floating-Point option, a domain +error shall occur and a NaN shall be returned. +.P +If +.IR x +is \(+-0, +\fItgamma\fR(), +\fItgammaf\fR(), +and +\fItgammal\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, and \(+-HUGE_VALL, +respectively. +On systems that support the IEC 60559 Floating-Point option, a pole +error shall occur; +otherwise, a +pole +error may occur. +.P +If the correct value would cause overflow, a range error shall occur +and +\fItgamma\fR(), +\fItgammaf\fR(), +and +\fItgammal\fR() +shall return \(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL, +respectively, with the same sign as the correct value of the function. +.P +If the correct value would cause underflow, +and is not representable, +a range error may occur, and +\fItgamma\fR(), +\fItgammaf\fR(), +and +\fItgammal\fR() +shall return +0.0, or +(if IEC 60559 Floating-Point is not supported) an implementation-defined +value no greater in magnitude than DBL_MIN, FLT_MIN, and LDBL_MIN, +respectively. +.P +If the correct value would cause underflow, and is representable, +a range error may occur and the correct value shall be returned. +.P +If +.IR x +is subnormal and 1/\c +.IR x +is representable, 1/\c +.IR x +should be returned. +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is +Inf, +.IR x +shall be returned. +.P +If +.IR x +is \-Inf, a domain error shall occur, and a NaN shall be returned. +.SH ERRORS +These functions shall fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is a negative integer, or +.IR x +is \-Inf. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.br +.RE +.IP "Range\ Error" 12 +The value overflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.P +These functions may fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is a negative integer. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The result underflows. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) +is non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +This function is named +\fItgamma\fR() +in order to avoid conflicts with the historical +.IR gamma (\|) +and +\fIlgamma\fR() +functions. +.SH "FUTURE DIRECTIONS" +It is possible that the error response for a negative integer argument +may be changed to a pole error and a return value of \(+-Inf. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIlgamma\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/time.3p b/upstream/archlinux/man3p/time.3p new file mode 100644 index 00000000..e26345ba --- /dev/null +++ b/upstream/archlinux/man3p/time.3p @@ -0,0 +1,209 @@ +'\" et +.TH TIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +time +\(em get time +.SH SYNOPSIS +.LP +.nf +#include +.P +time_t time(time_t *\fItloc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItime\fR() +function shall return the value of time +in seconds since the Epoch. +.P +The +.IR tloc +argument points to an area where the return value is also stored. If +.IR tloc +is a null pointer, no value is stored. +.SH "RETURN VALUE" +Upon successful completion, +\fItime\fR() +shall return the value of time. Otherwise, (\fBtime_t\fP)\-1 shall be +returned. +.SH ERRORS +The +\fItime\fR() +function may fail if: +.TP +.BR EOVERFLOW +The number of seconds since the Epoch will not fit in an object of type +.BR time_t . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Getting the Current Time" +.P +The following example uses the +\fItime\fR() +function to calculate the time elapsed, in seconds, since the Epoch, +\fIlocaltime\fR() +to convert that value to a broken-down time, and +\fIasctime\fR() +to convert the broken-down time values into a printable string. +.sp +.RS 4 +.nf + +#include +#include +.P +int main(void) +{ +time_t result; +.P + result = time(NULL); + printf("%s%ju secs since the Epoch\en", + asctime(localtime(&result)), + (uintmax_t)result); + return(0); +} +.fi +.P +.RE +.P +This example writes the current time to +.IR stdout +in a form like this: +.sp +.RS 4 +.nf + +Wed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +.fi +.P +.RE +.SS "Timing an Event" +.P +The following example gets the current time, prints it out in the +user's format, and prints the number of minutes to an event being +timed. +.sp +.RS 4 +.nf + +#include +#include +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +minutes_to_event = ...; +printf("The time is "); +puts(asctime(localtime(&now))); +printf("There are %d minutes to the event.\en", + minutes_to_event); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The +\fItime\fR() +function returns a value in seconds while +\fIclock_gettime\fR() +and +\fIgettimeofday\fR() +return a +.BR "struct timespec" +(seconds and nanoseconds) and +.BR "struct timeval" +(seconds and microseconds), respectively, and are therefore capable of +returning more precise times. The +\fItimes\fR() +function is also capable of more precision than +\fItime\fR() +as it returns a value in clock ticks, although it returns the elapsed time +since an arbitrary point such as system boot time, not since the epoch. +.P +Implementations in which +.BR time_t +is a 32-bit signed integer (many historical implementations) fail in +the year 2038. POSIX.1\(hy2008 does not address this problem. However, the use +of the +.BR time_t +type is mandated in order to ease the eventual fix. +.P +On some systems the +\fItime\fR() +function is implemented using a system call that does not return an +error condition in addition to the return value. On these systems it is +impossible to differentiate between valid and invalid return values and +hence overflow conditions cannot be reliably detected. +.P +The use of the +.IR +header instead of +.IR +allows compatibility with the ISO\ C standard. +.P +Many historical implementations (including Version 7) and the 1984 /usr/group standard use +.BR long +instead of +.BR time_t . +This volume of POSIX.1\(hy2017 uses the latter type in order to agree with the ISO\ C standard. +.SH "FUTURE DIRECTIONS" +In a future version of this volume of POSIX.1\(hy2017, +.BR time_t +is likely to be required to be capable of representing times far in the +future. Whether this will be mandated as a 64-bit type or a requirement +that a specific date in the future be representable (for example, 10000 +AD) is not yet determined. Systems purchased after the approval of this volume of POSIX.1\(hy2017 +should be evaluated to determine whether their lifetime will extend +past 2038. +.SH "SEE ALSO" +.IR "\fIasctime\fR\^(\|)", +.IR "\fIclock\fR\^(\|)", +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)", +.IR "\fIgettimeofday\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItimes\fR\^(\|)", +.IR "\fIutime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/timer_create.3p b/upstream/archlinux/man3p/timer_create.3p new file mode 100644 index 00000000..2c53fe68 --- /dev/null +++ b/upstream/archlinux/man3p/timer_create.3p @@ -0,0 +1,265 @@ +'\" et +.TH TIMER_CREATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +timer_create +\(em create a per-process timer +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int timer_create(clockid_t \fIclockid\fP, struct sigevent *restrict \fIevp\fP, + timer_t *restrict \fItimerid\fP); +.fi +.SH DESCRIPTION +The +\fItimer_create\fR() +function shall create a per-process timer using the specified clock, +.IR clock_id , +as the timing base. The +\fItimer_create\fR() +function shall return, in the location referenced by +.IR timerid , +a timer ID of type +.BR timer_t +used to identify the timer in timer requests. This timer ID shall be +unique within the calling process until the timer is deleted. The +particular clock, +.IR clock_id , +is defined in +.IR . +The timer whose ID is returned shall be in a disarmed state upon return +from +\fItimer_create\fR(). +.P +The +.IR evp +argument, if non-NULL, points to a +.BR sigevent +structure. This structure, allocated by the application, defines the +asynchronous notification to occur as specified in +.IR "Section 2.4.1" ", " "Signal Generation and Delivery" +when the timer expires. If the +.IR evp +argument is NULL, the effect is as if the +.IR evp +argument pointed to a +.BR sigevent +structure with the +.IR sigev_notify +member having the value SIGEV_SIGNAL, the +.IR sigev_signo +having a default signal number, and the +.IR sigev_value +member having the value of the timer ID. +.P +Each implementation shall define a set of clocks that can be used as +timing bases for per-process timers. All implementations shall support a +.IR clock_id +of CLOCK_REALTIME. +If the Monotonic Clock option is supported, implementations shall +support a +.IR clock_id +of CLOCK_MONOTONIC. +.P +Per-process timers shall not be inherited by a child process across a +\fIfork\fR() +and shall be disarmed and deleted by an +.IR exec . +.P +If _POSIX_CPUTIME is defined, implementations shall support +.IR clock_id +values representing the CPU-time clock of the calling process. +.P +If _POSIX_THREAD_CPUTIME is defined, implementations shall support +.IR clock_id +values representing the CPU-time clock of the calling thread. +.P +It is implementation-defined whether a +\fItimer_create\fR() +function will succeed if the value defined by +.IR clock_id +corresponds to the CPU-time clock of a process or thread different from +the process or thread invoking the function. +.P +If \fIevp\fR\->\fIsigev_sigev_notify\fR is SIGEV_THREAD and +\fIsev\fR\->\fIsigev_notify_attributes\fR is not NULL, if the attribute +pointed to by \fIsev\fR\->\fIsigev_notify_attributes\fR has a thread +stack address specified by a call to +\fIpthread_attr_setstack\fR(), +the results are unspecified if the signal is generated more than once. +.SH "RETURN VALUE" +If the call succeeds, +\fItimer_create\fR() +shall return zero and update the location referenced by +.IR timerid +to a +.BR timer_t , +which can be passed to the per-process timer calls. If an error +occurs, the function shall return a value of \-1 and set +.IR errno +to indicate the error. The value of +.IR timerid +is undefined if an error occurs. +.SH ERRORS +The +\fItimer_create\fR() +function shall fail if: +.TP +.BR EAGAIN +The system lacks sufficient signal queuing resources to honor the +request. +.TP +.BR EAGAIN +The calling process has already created all of the timers it is allowed +by this implementation. +.TP +.BR EINVAL +The specified clock ID is not defined. +.TP +.BR ENOTSUP +The implementation does not support the creation of a timer attached to +the CPU-time clock that is specified by +.IR clock_id +and associated with a process or thread different from the process or +thread invoking +\fItimer_create\fR(). +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If a timer is created which has \fIevp\fR\->\fIsigev_sigev_notify\fR +set to SIGEV_THREAD and the attribute pointed to by +\fIevp\fR\->\fIsigev_notify_attributes\fR has a thread stack address +specified by a call to +\fIpthread_attr_setstack\fR(), +the memory dedicated as a thread stack cannot be recovered. The reason +for this is that the threads created in response to a timer expiration +are created detached, or in an unspecified way if the thread +attribute's +.IR detachstate +is PTHREAD_CREATE_JOINABLE. In neither case is it valid to call +\fIpthread_join\fR(), +which makes it impossible to determine the lifetime of the created +thread which thus means the stack memory cannot be reused. +.br +.SH RATIONALE +.SS "Periodic Timer Overrun and Resource Allocation" +.P +The specified timer facilities may deliver realtime signals (that is, +queued signals) on implementations that support this option. Since +realtime applications cannot afford to lose notifications of +asynchronous events, like timer expirations or asynchronous I/O +completions, it must be possible to ensure that sufficient resources +exist to deliver the signal when the event occurs. In general, this is +not a difficulty because there is a one-to-one correspondence between a +request and a subsequent signal generation. If the request cannot +allocate the signal delivery resources, it can fail the call with an +.BR [EAGAIN] +error. +.P +Periodic timers are a special case. A single request can generate an +unspecified number of signals. This is not a problem if the +requesting process can service the signals as fast as they are +generated, thus making the signal delivery resources available for +delivery of subsequent periodic timer expiration signals. But, in +general, this cannot be assured\(emprocessing of periodic timer signals +may ``overrun''; that is, subsequent periodic timer expirations may +occur before the currently pending signal has been delivered. +.P +Also, for signals, according to the POSIX.1\(hy1990 standard, if subsequent occurrences of +a pending signal are generated, it is implementation-defined whether +a signal is delivered for each occurrence. This is not adequate for +some realtime applications. So a mechanism is required to allow +applications to detect how many timer expirations were delayed without +requiring an indefinite amount of system resources to store the delayed +expirations. +.P +The specified facilities provide for an overrun count. The overrun +count is defined as the number of extra timer expirations that occurred +between the time a timer expiration signal is generated and the time +the signal is delivered. The signal-catching function, if it is +concerned with overruns, can retrieve this count on entry. With this +method, a periodic timer only needs one ``signal queuing resource'' +that can be allocated at the time of the +\fItimer_create\fR() +function call. +.P +A function is defined to retrieve the overrun count so that an +application need not allocate static storage to contain the count, and +an implementation need not update this storage asynchronously on timer +expirations. But, for some high-frequency periodic applications, the +overhead of an additional system call on each timer expiration may be +prohibitive. The functions, as defined, permit an implementation to +maintain the overrun count in user space, associated with the +.IR timerid . +The +\fItimer_getoverrun\fR() +function can then be implemented as a macro that uses the +.IR timerid +argument (which may just be a pointer to a user space structure +containing the counter) to locate the overrun count with no system call +overhead. Other implementations, less concerned with this class of +applications, can avoid the asynchronous update of user space by +maintaining the count in a system structure at the cost of the extra +system call to obtain it. +.SS "Timer Expiration Signal Parameters" +.P +The Realtime Signals Extension option supports an application-specific +datum that is delivered to the extended signal handler. This value is +explicitly specified by the application, along with the signal number +to be delivered, in a +.BR sigevent +structure. The type of the application-defined value can be either an +integer constant or a pointer. This explicit specification of the +value, as opposed to always sending the +timer ID, was selected based on existing practice. +.P +It is common practice for realtime applications (on non-POSIX systems +or realtime extended POSIX systems) to use the parameters of event +handlers as the case label of a switch statement or as a pointer to an +application-defined data structure. Since +.IR timer_id s +are dynamically allocated by the +\fItimer_create\fR() +function, they can be used for neither of these functions without +additional application overhead in the signal handler; for example, to +search an array of saved timer IDs to associate the ID with a constant +or application data structure. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_delete\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/timer_delete.3p b/upstream/archlinux/man3p/timer_delete.3p new file mode 100644 index 00000000..1b0b20a8 --- /dev/null +++ b/upstream/archlinux/man3p/timer_delete.3p @@ -0,0 +1,92 @@ +'\" et +.TH TIMER_DELETE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +timer_delete +\(em delete a per-process timer +.SH SYNOPSIS +.LP +.nf +#include +.P +int timer_delete(timer_t \fItimerid\fP); +.fi +.SH DESCRIPTION +The +\fItimer_delete\fR() +function deletes the specified timer, +.IR timerid , +previously created by the +\fItimer_create\fR() +function. If the timer is armed when +\fItimer_delete\fR() +is called, the behavior shall be as if the timer is automatically +disarmed before removal. The disposition of pending signals for the +deleted timer is unspecified. +.P +The behavior is undefined if the value specified by the +.IR timerid +argument to +\fItimer_delete\fR() +does not correspond to a timer ID returned by +\fItimer_create\fR() +but not yet deleted by +\fItimer_delete\fR(). +.SH "RETURN VALUE" +If successful, the +\fItimer_delete\fR() +function shall return a value of zero. Otherwise, the function shall +return a value of \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +If an implementation detects that the value specified by the +.IR timerid +argument to +\fItimer_delete\fR() +does not correspond to a timer ID returned by +\fItimer_create\fR() +but not yet deleted by +\fItimer_delete\fR(), +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/timer_getoverrun.3p b/upstream/archlinux/man3p/timer_getoverrun.3p new file mode 100644 index 00000000..d243b6b9 --- /dev/null +++ b/upstream/archlinux/man3p/timer_getoverrun.3p @@ -0,0 +1,275 @@ +'\" et +.TH TIMER_GETOVERRUN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +timer_getoverrun, +timer_gettime, +timer_settime +\(em per-process timers +.SH SYNOPSIS +.LP +.nf +#include +.P +int timer_getoverrun(timer_t \fItimerid\fP); +int timer_gettime(timer_t \fItimerid\fP, struct itimerspec *\fIvalue\fP); +int timer_settime(timer_t \fItimerid\fP, int \fIflags\fP, + const struct itimerspec *restrict \fIvalue\fP, + struct itimerspec *restrict \fIovalue\fP); +.fi +.SH DESCRIPTION +The +\fItimer_gettime\fR() +function shall store the amount of time until the specified timer, +.IR timerid , +expires and the reload value of the timer into the space pointed to by +the +.IR value +argument. The +.IR it_value +member of this structure shall contain 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 +.IR it_interval +member of +.IR value +shall contain the reload value last set by +\fItimer_settime\fR(). +.P +The +\fItimer_settime\fR() +function shall set the time until the next expiration of the timer +specified by +.IR timerid +from the +.IR it_value +member of the +.IR value +argument and arm the timer if the +.IR it_value +member of +.IR value +is non-zero. If the specified timer was already armed when +\fItimer_settime\fR() +is called, this call shall reset the time until next expiration to the +.IR value +specified. If the +.IR it_value +member of +.IR value +is zero, the timer shall be disarmed. The effect of disarming or +resetting a timer with pending expiration notifications is unspecified. +.P +If the flag TIMER_ABSTIME is not set in the argument +.IR flags , +\fItimer_settime\fR() +shall behave as if the time until next expiration is set to be equal +to the interval specified by the +.IR it_value +member of +.IR value . +That is, the timer shall expire in +.IR it_value +nanoseconds from when the call is made. If the flag TIMER_ABSTIME is +set in the argument +.IR flags , +\fItimer_settime\fR() +shall behave as if the time until next expiration is set to be equal +to the difference between the absolute time specified by the +.IR it_value +member of +.IR value +and the current value of the clock associated with +.IR timerid . +That is, the timer shall expire when the clock reaches the value +specified by the +.IR it_value +member of +.IR value . +If the specified time has already passed, the function shall succeed +and the expiration notification shall be made. +.P +The reload value of the timer shall be set to the value specified by the +.IR it_interval +member of +.IR value . +When a timer is armed with a non-zero +.IR it_interval , +a periodic (or repetitive) timer is specified. +.P +Time values that are between two consecutive non-negative integer +multiples of the resolution of the specified timer shall be rounded up +to the larger multiple of the resolution. Quantization error shall not +cause the timer to expire earlier than the rounded time value. +.P +If the argument +.IR ovalue +is not NULL, the +\fItimer_settime\fR() +function shall store, in the location referenced by +.IR 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 shall not expire before their +scheduled time. +.P +Only a single signal shall be 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 shall be queued, and a timer overrun shall occur. +When a timer expiration signal is delivered to or accepted by a +process, the +\fItimer_getoverrun\fR() +function shall return 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 delivered or accepted, up to but not +including an implementation-defined maximum of +{DELAYTIMER_MAX}. +If the number of such extra expirations is greater than or equal to +{DELAYTIMER_MAX}, +then the overrun count shall be set to +{DELAYTIMER_MAX}. +The value returned by +\fItimer_getoverrun\fR() +shall apply to the most recent expiration signal delivery or acceptance +for the timer. If no expiration signal has been delivered for the timer, +the return value of +\fItimer_getoverrun\fR() +is unspecified. +.P +The behavior is undefined if the value specified by the +.IR timerid +argument to +\fItimer_getoverrun\fR(), +\fItimer_gettime\fR(), +or +\fItimer_settime\fR() +does not correspond to a timer ID returned by +\fItimer_create\fR() +but not yet deleted by +\fItimer_delete\fR(). +.SH "RETURN VALUE" +If the +\fItimer_getoverrun\fR() +function succeeds, it shall return the timer expiration overrun count +as explained above. +.P +If the +\fItimer_gettime\fR() +or +\fItimer_settime\fR() +functions succeed, a value of 0 shall be returned. +.P +If an error occurs for any of these functions, the value \-1 shall be +returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItimer_settime\fR() +function shall fail if: +.TP +.BR EINVAL +A +.IR value +structure specified a nanosecond value less than zero or greater than +or equal to 1\|000 million, and the +.IR it_value +member of that structure did not specify zero seconds and nanoseconds. +.P +The +\fItimer_settime\fR() +function may fail if: +.TP +.BR EINVAL +The +.IR it_interval +member of +.IR value +is not zero and the timer was created with notification by creation of +a new thread (\c +.IR sigev_sigev_notify +was SIGEV_THREAD) and a fixed stack address has been set in the thread +attribute pointed to by +.IR sigev_notify_attributes . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Using fixed stack addresses is problematic when timer expiration is +signaled by the creation of a new thread. Since it cannot be assumed +that the thread created for one expiration is finished before the next +expiration of the timer, it could happen that two threads use the same +memory as a stack at the same time. This is invalid and produces +undefined results. +.SH RATIONALE +Practical clocks tick at a finite rate, with rates of 100 hertz and +1\|000 hertz being common. The inverse of this tick rate is the clock +resolution, also called the clock granularity, which in either case is +expressed as a time duration, being 10 milliseconds and 1 millisecond +respectively for these common rates. The granularity of practical +clocks implies that if one reads a given clock twice in rapid +succession, one may get the same time value twice; and that timers must +wait for the next clock tick after the theoretical expiration time, to +ensure that a timer never returns too soon. Note also that the +granularity of the clock may be significantly coarser than the +resolution of the data format used to set and get time and interval +values. Also note that some implementations may choose to adjust time +and/or interval values to exactly match the ticks of the underlying +clock. +.P +This volume of POSIX.1\(hy2017 defines functions that allow an application to determine +the implementation-supported resolution for the clocks and requires an +implementation to document the resolution supported for timers and +\fInanosleep\fR() +if they differ from the supported clock resolution. This is more of a +procurement issue than a runtime application issue. +.P +If an implementation detects that the value specified by the +.IR timerid +argument to +\fItimer_getoverrun\fR(), +\fItimer_gettime\fR(), +or +\fItimer_settime\fR() +does not correspond to a timer ID returned by +\fItimer_create\fR() +but not yet deleted by +\fItimer_delete\fR(), +it is recommended that the function should fail and report an +.BR [EINVAL] +error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclock_getres\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/times.3p b/upstream/archlinux/man3p/times.3p new file mode 100644 index 00000000..5e7b93e6 --- /dev/null +++ b/upstream/archlinux/man3p/times.3p @@ -0,0 +1,214 @@ +'\" et +.TH TIMES "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +times +\(em get process and waited-for child process times +.SH SYNOPSIS +.LP +.nf +#include +.P +clock_t times(struct tms *\fIbuffer\fP); +.fi +.SH DESCRIPTION +The +\fItimes\fR() +function shall fill the +.BR tms +structure pointed to by +.IR buffer +with time-accounting information. The +.BR tms +structure is defined in +.IR . +.P +All times are measured in terms of the number of clock ticks used. +.P +The times of a terminated child process shall be included in the +.IR tms_cutime +and +.IR tms_cstime +elements of the parent when +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +returns the process ID of this terminated child. If a child process +has not waited for its children, their times shall not be included in +its times. +.IP " *" 4 +The +.IR tms_utime +structure member is the CPU time charged for the execution of user +instructions of the calling process. +.IP " *" 4 +The +.IR tms_stime +structure member is the CPU time charged for execution by the system on +behalf of the calling process. +.IP " *" 4 +The +.IR tms_cutime +structure member is the sum of the +.IR tms_utime +and +.IR tms_cutime +times of the child processes. +.IP " *" 4 +The +.IR tms_cstime +structure member is the sum of the +.IR tms_stime +and +.IR tms_cstime +times of the child processes. +.SH "RETURN VALUE" +Upon successful completion, +\fItimes\fR() +shall return the elapsed real time, in clock ticks, since an arbitrary +point in the past (for example, system start-up time). This point does +not change from one invocation of +\fItimes\fR() +within the process to another. The return value may overflow the +possible range of type +.BR clock_t . +If +\fItimes\fR() +fails, (\fBclock_t\fR)\-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItimes\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The return value would overflow the range of +.BR clock_t . +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Timing a Database Lookup" +.P +The following example defines two functions, +\fIstart_clock\fR() +and +\fIend_clock\fR(), +that are used to time a lookup. It also defines variables of type +.BR clock_t +and +.BR tms +to measure the duration of transactions. The +\fIstart_clock\fR() +function saves the beginning times given by the +\fItimes\fR() +function. The +\fIend_clock\fR() +function gets the ending times and prints the difference between the +two times. +.sp +.RS 4 +.nf + +#include +#include +\&... +void start_clock(void); +void end_clock(char *msg); +\&... +static clock_t st_time; +static clock_t en_time; +static struct tms st_cpu; +static struct tms en_cpu; +\&... +void +start_clock() +{ + st_time = times(&st_cpu); +} +.P +/* This example assumes that the result of each subtraction + is within the range of values that can be represented in + an integer type. */ +void +end_clock(char *msg) +{ + en_time = times(&en_cpu); +.P + fputs(msg,stdout); + printf("Real Time: %jd, User Time %jd, System Time %jd\en", + (intmax_t)(en_time - st_time), + (intmax_t)(en_cpu.tms_utime - st_cpu.tms_utime), + (intmax_t)(en_cpu.tms_stime - st_cpu.tms_stime)); +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +Applications should use \fIsysconf\fP(_SC_CLK_TCK) +to determine the number of clock ticks per second as it may vary from +system to system. +.SH RATIONALE +The accuracy of the times reported is intentionally left unspecified to +allow implementations flexibility in design, from uniprocessor to +multi-processor networks. +.P +The inclusion of times of child processes is recursive, so that a +parent process may collect the total times of all of its descendants. +But the times of a child are only added to those of its parent when its +parent successfully waits on the child. Thus, it is not guaranteed +that a parent process can always see the total times of all its +descendants; see also the discussion of the term ``realtime'' in +.IR "\fIalarm\fR\^(\|)". +.P +If the type +.BR clock_t +is defined to be a signed 32-bit integer, it overflows in somewhat more +than a year if there are 60 clock ticks per second, +or less than a year if there are 100. There are individual systems +that run continuously for longer than that. This volume of POSIX.1\(hy2017 permits an +implementation to make the reference point for the returned value be +the start-up time of the process, rather than system start-up time. +.P +The term ``charge'' in this context has nothing to do with billing +for services. The operating system accounts for time used in this +way. That information must be correct, regardless of how that +information is used. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIalarm\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fIfork\fR\^(\|)", +.IR "\fIsysconf\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIwait\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/timezone.3p b/upstream/archlinux/man3p/timezone.3p new file mode 100644 index 00000000..d708194f --- /dev/null +++ b/upstream/archlinux/man3p/timezone.3p @@ -0,0 +1,40 @@ +'\" et +.TH TIMEZONE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +timezone +\(em difference from UTC and local standard time +.SH SYNOPSIS +.LP +.nf +#include +.P +extern long timezone; +.fi +.SH DESCRIPTION +Refer to +.IR "\fItzset\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tmpfile.3p b/upstream/archlinux/man3p/tmpfile.3p new file mode 100644 index 00000000..be5d7b4f --- /dev/null +++ b/upstream/archlinux/man3p/tmpfile.3p @@ -0,0 +1,152 @@ +'\" et +.TH TMPFILE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tmpfile +\(em create a temporary file +.SH SYNOPSIS +.LP +.nf +#include +.P +FILE *tmpfile(void); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItmpfile\fR() +function shall create a temporary file and open a corresponding +stream. The file shall be automatically deleted when all references +to the file are closed. The file shall be opened as in +\fIfopen\fR() +for update (\fIwb\fP+), except that implementations may restrict the +permissions, either by clearing the file mode bits or setting them +to the value S_IRUSR | S_IWUSR. +.P +In some implementations, a permanent file may be left behind if +the process calling +\fItmpfile\fR() +is killed while it is processing a call to +\fItmpfile\fR(). +.P +An error message may be written to standard error if the stream cannot +be opened. +.SH "RETURN VALUE" +Upon successful completion, +\fItmpfile\fR() +shall return a pointer to the stream of the file that is created. +Otherwise, it shall return a null pointer +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fItmpfile\fR() +function shall fail if: +.TP +.BR EINTR +A signal was caught during +\fItmpfile\fR(). +.TP +.BR EMFILE +All file descriptors available to the process are currently open. +.TP +.BR EMFILE +{STREAM_MAX} +streams are currently open in the calling process. +.TP +.BR ENFILE +The maximum allowable number of files is currently open in the system. +.TP +.BR ENOSPC +The directory or file system which would contain the new file cannot be +expanded. +.TP +.BR EOVERFLOW +The file is a regular file and the size of the file cannot be +represented correctly in an object of type +.BR off_t . +.P +The +\fItmpfile\fR() +function may fail if: +.TP +.BR EMFILE +{FOPEN_MAX} +streams are currently open in the calling process. +.TP +.BR ENOMEM +Insufficient storage space is available. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Creating a Temporary File" +.P +The following example creates a temporary file for update, and returns +a pointer to a stream for the created file in the +.IR fp +variable. +.sp +.RS 4 +.nf + +#include +\&... +FILE *fp; +.P +fp = tmpfile (); +.fi +.P +.RE +.SH "APPLICATION USAGE" +It should be possible to open at least +{TMP_MAX} +temporary files during the lifetime of the program (this limit may be +shared with +\fItmpnam\fR()) +and there should be no limit on the number simultaneously open other +than this limit and any limit on the number of open file descriptors +or streams (\c +{OPEN_MAX}, +{FOPEN_MAX}, +{STREAM_MAX}). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfopen\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fItmpnam\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tmpnam.3p b/upstream/archlinux/man3p/tmpnam.3p new file mode 100644 index 00000000..4058a323 --- /dev/null +++ b/upstream/archlinux/man3p/tmpnam.3p @@ -0,0 +1,148 @@ +'\" et +.TH TMPNAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tmpnam +\(em create a name for a temporary file +.SH SYNOPSIS +.LP +.nf +#include +.P +char *tmpnam(char *\fIs\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItmpnam\fR() +function shall generate a string that is a valid pathname that does not +name an existing file. The function is potentially capable of generating +{TMP_MAX} +different strings, but any or all of them may already be in use by +existing files and thus not be suitable return values. +.P +The +\fItmpnam\fR() +function generates a different string each time it is called from the +same process, up to +{TMP_MAX} +times. If it is called more than +{TMP_MAX} +times, the behavior is implementation-defined. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017, +except +\fItempnam\fR(), +calls +\fItmpnam\fR(). +.P +The +\fItmpnam\fR() +function need not be thread-safe if called with a NULL parameter. +.SH "RETURN VALUE" +Upon successful completion, +\fItmpnam\fR() +shall return a pointer to a string. If no suitable string can be +generated, the +\fItmpnam\fR() +function shall return a null pointer. +.P +If the argument +.IR s +is a null pointer, +\fItmpnam\fR() +shall leave its result in an internal static object and return a +pointer to that object. Subsequent calls to +\fItmpnam\fR() +may modify the same object. If the argument +.IR s +is not a null pointer, it is presumed to point to an array of at least +L_tmpnam +.BR char s; +\fItmpnam\fR() +shall write its result in that array and shall return the argument +as its value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Generating a Pathname" +.P +The following example generates a unique pathname and stores it in the +array pointed to by +.IR ptr . +.sp +.RS 4 +.nf + +#include +\&... +char pathname[L_tmpnam+1]; +char *ptr; +.P +ptr = tmpnam(pathname); +.fi +.P +.RE +.SH "APPLICATION USAGE" +This function only creates pathnames. It is the application's +responsibility to create and remove the files. +.P +Between the time a pathname is created and the file is opened, it is +possible for some other process to create a file with the same name. +Applications may find +\fItmpfile\fR() +more useful. +.P +Applications should use the +\fItmpfile\fR(), +\fImkstemp\fR(), +or +\fImkdtemp\fR() +functions instead of the obsolescent +\fItmpnam\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fItmpnam\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfopen\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fImkdtemp\fR\^(\|)", +.IR "\fItempnam\fR\^(\|)", +.IR "\fItmpfile\fR\^(\|)", +.IR "\fIunlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/toascii.3p b/upstream/archlinux/man3p/toascii.3p new file mode 100644 index 00000000..ec62075c --- /dev/null +++ b/upstream/archlinux/man3p/toascii.3p @@ -0,0 +1,66 @@ +'\" et +.TH TOASCII "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +toascii +\(em translate an integer to a 7-bit ASCII character +.SH SYNOPSIS +.LP +.nf +#include +.P +int toascii(int \fIc\fP); +.fi +.SH DESCRIPTION +The +\fItoascii\fR() +function shall convert its argument into a 7-bit ASCII character. +.SH "RETURN VALUE" +The +\fItoascii\fR() +function shall return the value (\fIc\fP &0x7f). +.SH ERRORS +No errors are returned. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fItoascii\fR() +function cannot be used portably in a localized application. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fItoascii\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIisascii\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tolower.3p b/upstream/archlinux/man3p/tolower.3p new file mode 100644 index 00000000..8fd4dde7 --- /dev/null +++ b/upstream/archlinux/man3p/tolower.3p @@ -0,0 +1,102 @@ +'\" et +.TH TOLOWER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tolower, +tolower_l +\(em transliterate uppercase characters to lowercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int tolower(int \fIc\fP); +int tolower_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItolower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItolower\fR() +and +\fItolower_l\fR() +functions have as a domain a type +.BR int , +the value of which is representable as an +.BR "unsigned char" +or the value of EOF. If the argument has any other value, the behavior +is undefined. If the argument of +\fItolower\fR() +or +\fItolower_l\fR() +represents an uppercase letter, and there exists a corresponding +lowercase letter as defined by character type information in the current +locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding lowercase letter. All other +arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItolower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fItolower\fR() +and +\fItolower_l\fR() +functions shall return the lowercase letter corresponding to the +argument passed; otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/toupper.3p b/upstream/archlinux/man3p/toupper.3p new file mode 100644 index 00000000..a757d77f --- /dev/null +++ b/upstream/archlinux/man3p/toupper.3p @@ -0,0 +1,105 @@ +'\" et +.TH TOUPPER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +toupper, +toupper_l +\(em transliterate lowercase characters to uppercase +.SH SYNOPSIS +.LP +.nf +#include +.P +int toupper(int \fIc\fP); +int toupper_l(int \fIc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItoupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItoupper\fR() +and +\fItoupper_l\fR() +functions have as a domain a type +.BR int , +the value of which is representable as an +.BR "unsigned char" +or the value of EOF. If the argument has any other value, the behavior +is undefined. +.P +If the argument of +\fItoupper\fR() +or +\fItoupper_l\fR() +represents a lowercase letter, and there exists a corresponding +uppercase letter as defined by character type information in the current +locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding uppercase letter. +.P +All other arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItoupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fItoupper\fR() +and +\fItoupper_l\fR() +shall return the uppercase letter corresponding to the argument +passed; otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/towctrans.3p b/upstream/archlinux/man3p/towctrans.3p new file mode 100644 index 00000000..8ca233fc --- /dev/null +++ b/upstream/archlinux/man3p/towctrans.3p @@ -0,0 +1,157 @@ +'\" et +.TH TOWCTRANS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +towctrans, +towctrans_l +\(em wide-character transliteration +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t towctrans(wint_t \fIwc\fP, wctrans_t \fIdesc\fP); +wint_t towctrans_l(wint_t \fIwc\fP, wctrans_t \fIdesc\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItowctrans\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItowctrans\fR() +and +\fItowctrans_l\fR() +functions shall transliterate the wide-character code +.IR wc +using the mapping described by +.IR desc . +.P +The current setting of the +.IR LC_CTYPE +category in the current locale +or in the locale represented by +.IR locale , +respectively, should be the same as during the call to +\fIwctrans\fR() +or +\fIwctrans_l\fR() +that returned the value +.IR desc . +.P +If the value of +.IR desc +is invalid (that is, not obtained by a call to +\fIwctrans\fR() +or +.IR desc +is invalidated by a subsequent call to +\fIsetlocale\fR() +that has affected category +.IR LC_CTYPE ), +the result is unspecified. +.P +If the value of +.IR desc +is invalid (that is, not obtained by a call to +\fIwctrans_l\fR() +with the same locale object +.IR locale ) +the result is unspecified. +.P +An application wishing to check for error situations should set +.IR errno +to 0 before calling +\fItowctrans\fR() +or +\fItowctrans_l\fR(). +.P +If +.IR errno +is non-zero on return, an error has occurred. +.P +The behavior is undefined if the +.IR locale +argument to +\fItowctrans_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +If successful, the +\fItowctrans\fR() +and +\fItowctrans_l\fR() +functions shall return the mapped value of +.IR wc +using the mapping described by +.IR desc . +Otherwise, they shall return +.IR wc +unchanged. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +.IR desc +contains an invalid transliteration descriptor. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The strings +.BR \(dqtolower\(dq +and +.BR \(dqtoupper\(dq +are reserved for the standard mapping names. In the table below, the +functions in the left column are equivalent to the functions in the +right column. +.sp +.RS 4 +.nf + +towlower(\fIwc\fP) towctrans(\fIwc\fP, wctrans("tolower")) +towlower_l(\fIwc\fP, \fIlocale\fP) towctrans_l(\fIwc\fP, wctrans("tolower"), \fIlocale\fP) +towupper(\fIwc\fP) towctrans(\fIwc\fP, wctrans("toupper")) +towupper_l(\fIwc\fP, \fIlocale\fP) towctrans_l(\fIwc\fP, wctrans("toupper"), \fIlocale\fP) +.fi +.P +.RE +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItowlower\fR\^(\|)", +.IR "\fItowupper\fR\^(\|)", +.IR "\fIwctrans\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/towlower.3p b/upstream/archlinux/man3p/towlower.3p new file mode 100644 index 00000000..26791a78 --- /dev/null +++ b/upstream/archlinux/man3p/towlower.3p @@ -0,0 +1,105 @@ +'\" et +.TH TOWLOWER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +towlower, +towlower_l +\(em transliterate uppercase wide-character code to lowercase +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t towlower(wint_t \fIwc\fP); +wint_t towlower_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItowlower\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItowlower\fR() +and +\fItowlower_l\fR() +functions have as a domain a type +.BR wint_t , +the value of which the application shall ensure is a character +representable as a +.BR wchar_t , +and a wide-character code corresponding to a valid character in the +locale used by the function or the value of WEOF. +If the argument has any other value, the behavior is undefined. +If the argument of +\fItowlower\fR() +or +\fItowlower_l\fR() +represents an uppercase wide-character code, and there exists a +corresponding lowercase wide-character code as defined by character +type information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding lowercase wide-character code. +All other arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItowlower_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fItowlower\fR() +and +\fItowlower_l\fR() +functions shall return the lowercase letter corresponding to the +argument passed; otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/towupper.3p b/upstream/archlinux/man3p/towupper.3p new file mode 100644 index 00000000..cdc22b3b --- /dev/null +++ b/upstream/archlinux/man3p/towupper.3p @@ -0,0 +1,105 @@ +'\" et +.TH TOWUPPER "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +towupper, +towupper_l +\(em transliterate lowercase wide-character code to uppercase +.SH SYNOPSIS +.LP +.nf +#include +.P +wint_t towupper(wint_t \fIwc\fP); +wint_t towupper_l(wint_t \fIwc\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fItowupper\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fItowupper\fR() +and +\fItowupper_l\fR() +functions have as a domain a type +.BR wint_t , +the value of which the application shall ensure is a character +representable as a +.BR wchar_t , +and a wide-character code corresponding to a valid character in the +locale used by the function or the value of WEOF. +If the argument has any other value, the behavior is undefined. +If the argument of +\fItowupper\fR() +or +\fItowupper_l\fR() +represents a lowercase wide-character code, and there exists a +corresponding uppercase wide-character code as defined by character +type information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ), +the result shall be the corresponding uppercase wide-character code. +All other arguments in the domain are returned unchanged. +.P +The behavior is undefined if the +.IR locale +argument to +\fItowupper_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, the +\fItowupper\fR() +and +\fItowupper_l\fR() +functions shall return the uppercase letter corresponding to the +argument passed. Otherwise, they shall return the argument unchanged. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIuselocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/trunc.3p b/upstream/archlinux/man3p/trunc.3p new file mode 100644 index 00000000..4d4db8d2 --- /dev/null +++ b/upstream/archlinux/man3p/trunc.3p @@ -0,0 +1,87 @@ +'\" et +.TH TRUNC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +trunc, +truncf, +truncl +\(em round to truncated integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +double trunc(double \fIx\fP); +float truncf(float \fIx\fP); +long double truncl(long double \fIx\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall round their argument to the integer value, in +floating format, nearest to but no larger in magnitude than the +argument. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the truncated +integer value. +.br \" without this, margin code is on the line above +The result shall have the same sign as +.IR x . +.P +If +.IR x +is NaN, a NaN shall be returned. +.P +If +.IR x +is \(+-0 or \(+-Inf, +.IR x +shall be returned. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The integral value returned by these functions need not be expressible +as an +.BR intmax_t . +The return value should be tested before assigning it to an integer type +to avoid the undefined results of an integer overflow. +.P +These functions may raise the inexact floating-point exception if the +result differs in value from the argument. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/truncate.3p b/upstream/archlinux/man3p/truncate.3p new file mode 100644 index 00000000..12784964 --- /dev/null +++ b/upstream/archlinux/man3p/truncate.3p @@ -0,0 +1,168 @@ +'\" et +.TH TRUNCATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +truncate +\(em truncate a file to a specified length +.SH SYNOPSIS +.LP +.nf +#include +.P +int truncate(const char *\fIpath\fP, off_t \fIlength\fP); +.fi +.SH DESCRIPTION +The +\fItruncate\fR() +function shall cause the regular file named by +.IR path +to have a size which shall be equal to +.IR length +bytes. +.P +If the file previously was larger than +.IR length , +the extra data is discarded. If the file was previously shorter than +.IR length , +its size is increased, and the extended area appears as if it were +zero-filled. +.P +The application shall ensure that the process has write permission for +the file. +.P +If the request would cause the file size to exceed the soft file size +limit for the process, the request shall fail and the implementation +shall generate the SIGXFSZ signal for the process. +.P +The +\fItruncate\fR() +function shall not modify the file offset for any open file descriptions +associated with the file. Upon successful completion, +\fItruncate\fR() +shall mark for update the last data modification and last file status +change timestamps of the file, and the S_ISUID and S_ISGID bits of the +file mode may be cleared. +.SH "RETURN VALUE" +Upon successful completion, +\fItruncate\fR() +shall return 0. Otherwise, \-1 shall be returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fItruncate\fR() +function shall fail if: +.TP +.BR EINTR +A signal was caught during execution. +.TP +.BR EINVAL +The +.IR length +argument was less than 0. +.TP +.BR EFBIG " or " EINVAL +.br +The +.IR length +argument was greater than the maximum file size. +.TP +.BR EIO +An I/O error occurred while reading from or writing to a file system. +.TP +.BR EACCES +A component of the path prefix denies search permission, or write +permission is denied on the file. +.TP +.BR EISDIR +The named file is a directory. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EROFS +The named file resides on a read-only file system. +.br +.P +The +\fItruncate\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIopen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/truncf.3p b/upstream/archlinux/man3p/truncf.3p new file mode 100644 index 00000000..9df2c160 --- /dev/null +++ b/upstream/archlinux/man3p/truncf.3p @@ -0,0 +1,42 @@ +'\" et +.TH TRUNCF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +truncf, +truncl +\(em round to truncated integer value +.SH SYNOPSIS +.LP +.nf +#include +.P +float truncf(float \fIx\fP); +long double truncl(long double \fIx\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItrunc\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tsearch.3p b/upstream/archlinux/man3p/tsearch.3p new file mode 100644 index 00000000..28ed9e62 --- /dev/null +++ b/upstream/archlinux/man3p/tsearch.3p @@ -0,0 +1,41 @@ +'\" et +.TH TSEARCH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +tsearch +\(em search a binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void *tsearch(const void *\fIkey\fP, void **\fIrootp\fP, + int (*\fIcompar\fP)(const void *, const void *)); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItdelete\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ttyname.3p b/upstream/archlinux/man3p/ttyname.3p new file mode 100644 index 00000000..19036912 --- /dev/null +++ b/upstream/archlinux/man3p/ttyname.3p @@ -0,0 +1,134 @@ +'\" et +.TH TTYNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ttyname, +ttyname_r +\(em find the pathname of a terminal +.SH SYNOPSIS +.LP +.nf +#include +.P +char *ttyname(int \fIfildes\fP); +int ttyname_r(int \fIfildes\fP, char *\fIname\fP, size_t \fInamesize\fP); +.fi +.SH DESCRIPTION +The +\fIttyname\fR() +function shall return a pointer to a string containing a null-terminated +pathname of the terminal associated with file descriptor +.IR fildes . +The application shall not modify the string returned. The returned +pointer might be invalidated or the string content might be overwritten +by a subsequent call to +\fIttyname\fR(). +The returned pointer and the string content might also be invalidated +if the calling thread is terminated. +.P +The +\fIttyname\fR() +function need not be thread-safe. +.P +The +\fIttyname_r\fR() +function shall store the null-terminated pathname of the terminal +associated with the file descriptor +.IR fildes +in the character array referenced by +.IR name . +The array is +.IR namesize +characters long and should have space for the name and the terminating +null character. The maximum length of the terminal name shall be +{TTY_NAME_MAX}. +.SH "RETURN VALUE" +Upon successful completion, +\fIttyname\fR() +shall return a pointer to a string. Otherwise, a null pointer shall +be returned and +.IR errno +set to indicate the error. +.P +If successful, the +\fIttyname_r\fR() +function shall return zero. Otherwise, an error number shall be +returned to indicate the error. +.SH ERRORS +The +\fIttyname\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a terminal. +.P +The +\fIttyname_r\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor. +.TP +.BR ENOTTY +The file associated with the +.IR fildes +argument is not a terminal. +.TP +.BR ERANGE +The value of +.IR namesize +is smaller than the length of the string to be returned including the +terminating null character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +The term ``terminal'' is used instead of the historical term +``terminal device'' in order to avoid a reference to an undefined +term. +.P +The thread-safe version places the terminal name in a user-supplied +buffer and returns a non-zero value if it fails. The non-thread-safe +version may return the name in a static data area that may be +overwritten by each call. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/twalk.3p b/upstream/archlinux/man3p/twalk.3p new file mode 100644 index 00000000..59c7ea6c --- /dev/null +++ b/upstream/archlinux/man3p/twalk.3p @@ -0,0 +1,41 @@ +'\" et +.TH TWALK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +twalk +\(em traverse a binary search tree +.SH SYNOPSIS +.LP +.nf +#include +.P +void twalk(const void *\fIroot\fP, + void (*\fIaction\fP)(const void *, VISIT, int )); +.fi +.SH DESCRIPTION +Refer to +.IR "\fItdelete\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/tzset.3p b/upstream/archlinux/man3p/tzset.3p new file mode 100644 index 00000000..5304dfb9 --- /dev/null +++ b/upstream/archlinux/man3p/tzset.3p @@ -0,0 +1,160 @@ +'\" et +.TH TZSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +daylight, +timezone, +tzname, +tzset +\(em set timezone conversion information +.SH SYNOPSIS +.LP +.nf +#include +.P +extern int daylight; +extern long timezone; +extern char *tzname[2]; +void tzset(void); +.fi +.SH DESCRIPTION +The +\fItzset\fR() +function shall use the value of the environment variable +.IR TZ +to set time conversion information used by +.IR "\fIctime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +and +.IR "\fIstrftime\fR\^(\|)". +If +.IR TZ +is absent from the environment, implementation-defined default +timezone information shall be used. +.P +The +\fItzset\fR() +function shall set the external variable +.IR tzname +as follows: +.sp +.RS 4 +.nf + +tzname[0] = "\fIstd\fP"; +tzname[1] = "\fIdst\fP"; +.fi +.P +.RE +.P +where +.IR std +and +.IR dst +are as described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables". +.P +The +\fItzset\fR() +function also shall set the external variable +.IR daylight +to 0 if Daylight Savings Time conversions should never be applied for +the timezone in use; otherwise, non-zero. The external variable +.IR timezone +shall be set to the difference, in seconds, between Coordinated +Universal Time (UTC) and local standard time. +.P +If a thread accesses +.IR tzname , +.IR daylight , +or +.IR timezone +directly while another thread is in a call to +\fItzset\fR(), +or to any function that is required or allowed to set timezone +information as if by calling +\fItzset\fR(), +the behavior is undefined. +.SH "RETURN VALUE" +The +\fItzset\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +Example +.IR TZ +variables and their timezone differences are given in the table below: +.TS +center box tab(!); +cI | cI +lw(1i) | lw(1i). +TZ!timezone +_ +EST5EDT!5*60*60 +GMT0!0*60*60 +JST-9!\-9*60*60 +MET-1MEST!\-1*60*60 +MST7MDT!7*60*60 +PST8PDT!8*60*60 +.TE +.SH "APPLICATION USAGE" +Since the +\fIctime\fR(), +\fIlocaltime\fR(), +\fImktime\fR(), +\fIstrftime\fR(), +and +\fIstrftime_l\fR() +functions are required to set timezone information as if by calling +\fItzset\fR(), +there is no need for an explicit +\fItzset\fR() +call before using these functions. However, portable applications +should call +\fItzset\fR() +explicitly before using +\fIctime_r\fR() +or +\fIlocaltime_r\fR() +because setting timezone information is optional for those functions. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIctime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ulimit.3p b/upstream/archlinux/man3p/ulimit.3p new file mode 100644 index 00000000..cbd8ca29 --- /dev/null +++ b/upstream/archlinux/man3p/ulimit.3p @@ -0,0 +1,134 @@ +'\" et +.TH ULIMIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ulimit +\(em get and set process limits +.SH SYNOPSIS +.LP +.nf +#include +.P +long ulimit(int \fIcmd\fP, ...); +.fi +.SH DESCRIPTION +The +\fIulimit\fR() +function shall control process limits. The process limits that can be +controlled by this function include the maximum size of a single file +that can be written (this is equivalent to using +\fIsetrlimit\fR() +with RLIMIT_FSIZE). The +.IR cmd +values, defined in +.IR , +include: +.IP UL_GETFSIZE 12 +Return the file size limit (RLIMIT_FSIZE) of the process. The limit +shall be in units of 512-byte blocks and shall be inherited by child +processes. Files of any size can be read. The return value shall be the +integer part of the soft file size limit divided by 512. If the result +cannot be represented as a +.BR long , +the result is unspecified. +.IP UL_SETFSIZE 12 +Set the file size limit for output operations of the process to the +value of the second argument, taken as a +.BR long , +multiplied by 512. If the result would overflow an +.BR rlim_t , +the actual value set is unspecified. Any process may decrease its own +limit, but only a process with appropriate privileges may increase the +limit. The return value shall be the integer part of the new file size +limit divided by 512. +.P +The +\fIulimit\fR() +function shall not change the setting of +.IR errno +if successful. +.P +As all return values are permissible in a successful situation, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIulimit\fR(), +and, if it returns \-1, check to see if +.IR errno +is non-zero. +.SH "RETURN VALUE" +Upon successful completion, +\fIulimit\fR() +shall return the value of the requested limit. Otherwise, \-1 +shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIulimit\fR() +function shall fail and the limit shall be unchanged if: +.TP +.BR EINVAL +The +.IR cmd +argument is not valid. +.TP +.BR EPERM +A process not having appropriate privileges attempts to increase its +file size limit. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the +\fIulimit\fR() +function uses type +.BR long +rather than +.BR rlim_t , +this function is not sufficient for file sizes on many current systems. +Applications should use the +\fIgetrlimit\fR() +or +\fIsetrlimit\fR() +functions instead of the obsolescent +\fIulimit\fR() +function. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +The +\fIulimit\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/umask.3p b/upstream/archlinux/man3p/umask.3p new file mode 100644 index 00000000..283a469f --- /dev/null +++ b/upstream/archlinux/man3p/umask.3p @@ -0,0 +1,118 @@ +'\" et +.TH UMASK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +umask +\(em set and get the file mode creation mask +.SH SYNOPSIS +.LP +.nf +#include +.P +mode_t umask(mode_t \fIcmask\fP); +.fi +.SH DESCRIPTION +The +\fIumask\fR() +function shall set the file mode creation mask of the process to +.IR cmask +and return the previous value of the mask. Only the file permission +bits of +.IR cmask +(see +.IR ) +are used; the meaning of the other bits is implementation-defined. +.P +The file mode creation mask of the process is used to turn off +permission bits in the +.IR mode +argument supplied during calls to the following functions: +.IP " *" 4 +\fIopen\fR(), +\fIopenat\fR(), +\fIcreat\fR(), +\fImkdir\fR(), +\fImkdirat\fR(), +\fImkfifo\fR(), +and +\fImkfifoat\fR() +.IP " *" 4 +\fImknod\fR(), +\fImknodat\fR() +.IP " *" 4 +\fImq_open\fR() +.IP " *" 4 +\fIsem_open\fR() +.P +Bit positions that are set in +.IR cmask +are cleared in the mode of the created file. +.SH "RETURN VALUE" +The file permission bits in the value returned by +\fIumask\fR() +shall be the previous value of the file mode creation mask. The state +of any other bits in that value is unspecified, except that a +subsequent call to +\fIumask\fR() +with the returned value as +.IR cmask +shall leave the state of the mask the same as its state before the +first call, including any unspecified use of those bits. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Unsigned argument and return types for +\fIumask\fR() +were proposed. The return type and the argument were both changed to +.BR mode_t . +.P +Historical implementations have made use of additional bits in +.IR cmask +for their implementation-defined purposes. The addition of the text +that the meaning of other bits of the field is implementation-defined +permits these implementations to conform to this volume of POSIX.1\(hy2017. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIcreat\fR\^(\|)", +.IR "\fIexec\fR\^", +.IR "\fImkdir\fR\^(\|)", +.IR "\fImkfifo\fR\^(\|)", +.IR "\fImknod\fR\^(\|)", +.IR "\fImq_open\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIsem_open\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/uname.3p b/upstream/archlinux/man3p/uname.3p new file mode 100644 index 00000000..34b82d2a --- /dev/null +++ b/upstream/archlinux/man3p/uname.3p @@ -0,0 +1,124 @@ +'\" et +.TH UNAME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +uname +\(em get the name of the current system +.SH SYNOPSIS +.LP +.nf +#include +.P +int uname(struct utsname *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIuname\fR() +function shall store information identifying the current system in the +structure pointed to by +.IR name . +.P +The +\fIuname\fR() +function uses the +.BR utsname +structure defined in +.IR . +.P +The +\fIuname\fR() +function shall return a string naming the current system in the +character array +.IR sysname . +Similarly, +.IR nodename +shall contain the name of this node within an implementation-defined +communications network. The arrays +.IR release +and +.IR version +shall further identify the operating system. The array +.IR machine +shall contain a name that identifies the hardware that the system +is running on. +.P +The format of each member is implementation-defined. +.SH "RETURN VALUE" +Upon successful completion, a non-negative value shall be returned. +Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The inclusion of the +.IR nodename +member in this structure does not imply that it is sufficient +information for interfacing to communications networks. +.SH RATIONALE +The values of the structure members are not constrained to have any +relation to the version of this volume of POSIX.1\(hy2017 implemented in the operating +system. An application should instead depend on _POSIX_VERSION +and related constants defined in +.IR . +.P +This volume of POSIX.1\(hy2017 does not define the sizes of the members of the structure +and permits them to be of different sizes, although most +implementations define them all to be the same size: eight bytes plus +one byte for the string terminator. That size for +.IR nodename +is not enough for use with many networks. +.P +The +\fIuname\fR() +function originated in System III, System V, and related +implementations, +and it does not exist in Version 7 or +4.3 BSD. The values it returns are set at system compile time in those +historical implementations. +.P +4.3 BSD has +\fIgethostname\fR() +and +\fIgethostid\fR(), +which return a symbolic name and a numeric value, respectively. There +are related +\fIsethostname\fR() +and +\fIsethostid\fR() +functions that are used to set the values the other two functions +return. The former functions are included in this specification, the +latter are not. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ungetc.3p b/upstream/archlinux/man3p/ungetc.3p new file mode 100644 index 00000000..28f452b5 --- /dev/null +++ b/upstream/archlinux/man3p/ungetc.3p @@ -0,0 +1,120 @@ +'\" et +.TH UNGETC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ungetc +\(em push byte back into input stream +.SH SYNOPSIS +.LP +.nf +#include +.P +int ungetc(int \fIc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIungetc\fR() +function shall push the byte specified by +.IR c +(converted to an +.BR "unsigned char" ) +back onto the input stream pointed to by +.IR stream . +The pushed-back bytes shall be returned by subsequent reads on that +stream in the reverse order of their pushing. A successful intervening +call (with the stream pointed to by +.IR stream ) +to a file-positioning function (\c +\fIfseek\fR(), +\c +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR()) +or +\fIfflush\fR() +shall discard any pushed-back bytes for the stream. The external +storage corresponding to the stream shall be unchanged. +.P +One byte of push-back shall be provided. If +\fIungetc\fR() +is called too many times on the same stream without an intervening read +or file-positioning operation on that stream, the operation may fail. +.P +If the value of +.IR c +equals that of the macro EOF, the operation shall fail and the input +stream shall be left unchanged. +.P +A successful call to +\fIungetc\fR() +shall clear the end-of-file indicator for the stream. The value of the +file-position indicator for the stream after all pushed-back bytes have +been read, or discarded by calling +\fIfseek\fR(), +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR() +(but not +\fIfflush\fR()), +shall be the same as it was before the bytes were pushed back. The +file-position indicator is decremented by each successful call to +\fIungetc\fR(); +if its value was 0 before a call, its value is unspecified after the call. +.SH "RETURN VALUE" +Upon successful completion, +\fIungetc\fR() +shall return the byte pushed back after conversion. Otherwise, it +shall return EOF. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIgetc\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/ungetwc.3p b/upstream/archlinux/man3p/ungetwc.3p new file mode 100644 index 00000000..b47bf9cc --- /dev/null +++ b/upstream/archlinux/man3p/ungetwc.3p @@ -0,0 +1,128 @@ +'\" et +.TH UNGETWC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +ungetwc +\(em push wide-character code back into the input stream +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +wint_t ungetwc(wint_t \fIwc\fP, FILE *\fIstream\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIungetwc\fR() +function shall push the character corresponding to the wide-character +code specified by +.IR wc +back onto the input stream pointed to by +.IR stream . +The pushed-back characters shall be returned by subsequent reads on that +stream in the reverse order of their pushing. A successful intervening +call (with the stream pointed to by +.IR stream ) +to a file-positioning function (\c +\fIfseek\fR(), +\c +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR()) +or +\fIfflush\fR() +shall discard any pushed-back characters for the stream. The external +storage corresponding to the stream is unchanged. +.P +At least one character of push-back shall be provided. If +\fIungetwc\fR() +is called too many times on the same stream without an intervening read +or file-positioning operation on that stream, the operation may fail. +.P +If the value of +.IR wc +equals that of the macro WEOF, the operation shall fail and the input +stream shall be left unchanged. +.P +A successful call to +\fIungetwc\fR() +shall clear the end-of-file indicator for the stream. The value of the +file-position indicator for the stream after all pushed-back characters +have been read, or discarded by calling +\fIfseek\fR(), +\c +\fIfseeko\fR(), +\fIfsetpos\fR(), +or +\fIrewind\fR() +(but not +\fIfflush\fR()), +shall be the same as it was before the characters were pushed back. The +file-position indicator is decremented (by one or more) by each successful +call to +\fIungetwc\fR(); +if its value was 0 before a call, its value is unspecified after the call. +.SH "RETURN VALUE" +Upon successful completion, +\fIungetwc\fR() +shall return the wide-character code corresponding to the pushed-back +character. Otherwise, it shall return WEOF. +.SH ERRORS +The +\fIungetwc\fR() +function may fail if: +.TP +.BR EILSEQ +An invalid character sequence is detected, or a wide-character code +does not correspond to a valid character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfseek\fR\^(\|)", +.IR "\fIfsetpos\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIrewind\fR\^(\|)", +.IR "\fIsetbuf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/unlink.3p b/upstream/archlinux/man3p/unlink.3p new file mode 100644 index 00000000..ee7069ae --- /dev/null +++ b/upstream/archlinux/man3p/unlink.3p @@ -0,0 +1,455 @@ +'\" et +.TH UNLINK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +unlink, unlinkat +\(em remove a directory entry +.SH SYNOPSIS +.LP +.nf +#include +.P +int unlink(const char *\fIpath\fP); +.P +#include +.P +int unlinkat(int \fIfd\fP, const char *\fIpath\fP, int \fIflag\fP); +.fi +.SH DESCRIPTION +The +\fIunlink\fR() +function shall remove a link to a file. If +.IR path +names a symbolic link, +\fIunlink\fR() +shall remove the symbolic link named by +.IR path +and shall not affect any file or directory named by the contents of the +symbolic link. Otherwise, +\fIunlink\fR() +shall remove the link named by the pathname pointed to by +.IR path +and shall decrement the link count of the file referenced by the link. +.P +When the file's link count becomes 0 and no process has the file open, +the space occupied by the file shall be freed and the file shall no +longer be accessible. If one or more processes have the file open when +the last link is removed, the link shall be removed before +\fIunlink\fR() +returns, but the removal of the file contents shall be postponed until +all references to the file are closed. +.P +The +.IR path +argument shall not name a directory unless the process has appropriate +privileges and the implementation supports using +\fIunlink\fR() +on directories. +.P +Upon successful completion, +\fIunlink\fR() +shall mark for update the last data modification and last file status +change timestamps of the parent directory. Also, if the file's link +count is not 0, the last file status change timestamp of the file shall +be marked for update. +.P +The +\fIunlinkat\fR() +function shall be equivalent to the +\fIunlink\fR() +or +\fIrmdir\fR() +function except in the case where +.IR path +specifies a relative path. In this case the directory entry to be +removed is determined relative to the directory associated with the +file descriptor +.IR fd +instead of the current working directory. If the access mode of the +open file description associated with the file descriptor is not +O_SEARCH, the function shall check whether directory searches are +permitted using the current permissions of the directory underlying +the file descriptor. If the access mode is O_SEARCH, the function +shall not perform the check. +.P +Values for +.IR flag +are constructed by a bitwise-inclusive OR of flags from the following +list, defined in +.IR : +.IP AT_REMOVEDIR 6 +.br +Remove the directory entry specified by +.IR fd +and +.IR path +as a directory, not a normal file. +.P +If +\fIunlinkat\fR() +is passed the special value AT_FDCWD in the +.IR fd +parameter, the current working directory shall be used and the behavior +shall be identical to a call to +\fIunlink\fR() +or +\fIrmdir\fR() +respectively, depending on whether or not the AT_REMOVEDIR bit is set in +.IR flag . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return 0. Otherwise, +these functions shall return \-1 and set +.IR errno +to indicate the error. If \-1 is returned, the named file shall not +be changed. +.SH ERRORS +These functions shall fail and shall not unlink the file if: +.TP +.BR EACCES +Search permission is denied for a component of the path prefix, or +write permission is denied on the directory containing the directory +entry to be removed. +.TP +.BR EBUSY +The file named by the +.IR path +argument cannot be unlinked because it is being used by the system or +another process and the implementation considers this an error. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The file named by +.IR path +is a directory, and either the calling process does not have +appropriate privileges, or the implementation prohibits using +\fIunlink\fR() +on directories. +.TP +.BR EPERM " or " EACCES +.br +The S_ISVTX flag is set on the directory containing the file referred +to by the +.IR path +argument and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection". +.TP +.BR EROFS +The directory entry to be unlinked is part of a read-only file system. +.P +The +\fIunlinkat\fR() +function shall fail if: +.TP +.BR EACCES +The access mode of the open file description associated with +.IR fd +is not O_SEARCH and the permissions of the directory underlying +.IR fd +do not permit directory searches. +.TP +.BR EBADF +The +.IR path +argument does not specify an absolute path and the +.IR fd +argument is neither AT_FDCWD nor a valid file descriptor open for reading +or searching. +.TP +.BR ENOTDIR +The +.IR path +argument is not an absolute path and +.IR fd +is a file descriptor associated with a non-directory file. +.TP +.BR EEXIST " or " ENOTEMPTY +.br +The +.IR flag +parameter has the AT_REMOVEDIR bit set and the +.IR path +argument names a directory that is not an empty directory, or there are +hard links to the directory other than dot or a single entry in dot-dot. +.TP +.BR ENOTDIR +The +.IR flag +parameter has the AT_REMOVEDIR bit set and +.IR path +does not name a directory. +.P +These functions may fail and not unlink the file if: +.TP +.BR EBUSY +The file named by +.IR path +is a named STREAM. +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.TP +.BR ETXTBSY +The entry to be unlinked is the last directory entry to a pure +procedure (shared text) file that is being executed. +.br +.P +The +\fIunlinkat\fR() +function may fail if: +.TP +.BR EINVAL +The value of the +.IR flag +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Removing a Link to a File" +.P +The following example shows how to remove a link to a file named +.BR /home/cnd/mod1 +by removing the entry named +.BR /modules/pass1 . +.sp +.RS 4 +.nf + +#include +.P +char *path = "/modules/pass1"; +int status; +\&... +status = unlink(path); +.fi +.P +.RE +.SS "Checking for an Error" +.P +The following example fragment creates a temporary password lock file +named +.BR LOCKFILE , +which is defined as +.BR /etc/ptmp , +and gets a file descriptor for it. If the file cannot be opened for +writing, +\fIunlink\fR() +is used to remove the link between the file descriptor and +.BR LOCKFILE . +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +.P +int pfd; /* Integer for file descriptor returned by open call. */ +FILE *fpfd; /* File pointer for use in putpwent(). */ +\&... +/* Open password Lock file. If it exists, this is an error. */ +if ((pfd = open(LOCKFILE, O_WRONLY| O_CREAT | O_EXCL, S_IRUSR + | S_IWUSR | S_IRGRP | S_IROTH)) == -1) { + fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en"); + exit(1); +} +.P +/* Lock file created; proceed with fdopen of lock file so that + putpwent() can be used. + */ +if ((fpfd = fdopen(pfd, "w")) == NULL) { + close(pfd); + unlink(LOCKFILE); + exit(1); +} +.fi +.P +.RE +.SS "Replacing Files" +.P +The following example fragment uses +\fIunlink\fR() +to discard links to files, so that they can be replaced with new +versions of the files. The first call removes the link to +.BR LOCKFILE +if an error occurs. Successive calls remove the links to +.BR SAVEFILE +and +.BR PASSWDFILE +so that new links can be created, then removes the link to +.BR LOCKFILE +when it is no longer needed. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +.P +#define LOCKFILE "/etc/ptmp" +#define PASSWDFILE "/etc/passwd" +#define SAVEFILE "/etc/opasswd" +\&... +/* If no change was made, assume error and leave passwd unchanged. */ +if (!valid_change) { + fprintf(stderr, "Could not change password for user %s\en", user); + unlink(LOCKFILE); + exit(1); +} +.P +/* Change permissions on new password file. */ +chmod(LOCKFILE, S_IRUSR | S_IRGRP | S_IROTH); +.P +/* Remove saved password file. */ +unlink(SAVEFILE); +.P +/* Save current password file. */ +link(PASSWDFILE, SAVEFILE); +.P +/* Remove current password file. */ +unlink(PASSWDFILE); +.P +/* Save new password file as current password file. */ +link(LOCKFILE,PASSWDFILE); +.P +/* Remove lock file. */ +unlink(LOCKFILE); +.P +exit(0); +.fi +.P +.RE +.SH "APPLICATION USAGE" +Applications should use +\fIrmdir\fR() +to remove a directory. +.SH RATIONALE +Unlinking a directory is restricted to the superuser +in many historical implementations for reasons given in +\fIlink\fR() +(see also +\fIrename\fR()). +.P +The meaning of +.BR [EBUSY] +in historical implementations is ``mount point busy''. Since this volume of POSIX.1\(hy2017 does +not cover the system administration concepts of mounting and unmounting, +the description of the error was changed to ``resource busy''. (This +meaning is used by some device drivers when a second process tries to +open an exclusive use device.) The wording is also intended to allow +implementations to refuse to remove a directory if it is the root or +current working directory of any process. +.P +The standard developers reviewed TR 24715\(hy2006 and noted that +LSB-conforming implementations may return +.BR [EISDIR] +instead of +.BR [EPERM] +when unlinking a directory. A change to permit this behavior by +changing the requirement for +.BR [EPERM] +to +.BR [EPERM] +or +.BR [EISDIR] +was considered, but decided against since it would break existing +strictly conforming and conforming applications. Applications written +for portability to both POSIX.1\(hy2008 and the LSB should be prepared to +handle either error code. +.P +The purpose of the +\fIunlinkat\fR() +function is to remove directory entries in directories other than the +current working directory without exposure to race conditions. Any part +of the path of a file could be changed in parallel to a call to +\fIunlink\fR(), +resulting in unspecified behavior. By opening a file descriptor for +the target directory and using the +\fIunlinkat\fR() +function it can be guaranteed that the removed directory entry is +located relative to the desired directory. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIclose\fR\^(\|)", +.IR "\fIlink\fR\^(\|)", +.IR "\fIremove\fR\^(\|)", +.IR "\fIrename\fR\^(\|)", +.IR "\fIrmdir\fR\^(\|)", +.IR "\fIsymlink\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.3" ", " "Directory Protection", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/unlockpt.3p b/upstream/archlinux/man3p/unlockpt.3p new file mode 100644 index 00000000..5933a43a --- /dev/null +++ b/upstream/archlinux/man3p/unlockpt.3p @@ -0,0 +1,87 @@ +'\" et +.TH UNLOCKPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +unlockpt +\(em unlock a pseudo-terminal master/slave pair +.SH SYNOPSIS +.LP +.nf +#include +.P +int unlockpt(int \fIfildes\fP); +.fi +.SH DESCRIPTION +The +\fIunlockpt\fR() +function shall unlock the slave pseudo-terminal device associated with +the master to which +.IR fildes +refers. +.P +Conforming applications shall ensure that they call +\fIunlockpt\fR() +before opening the slave side of a pseudo-terminal device. +.SH "RETURN VALUE" +Upon successful completion, +\fIunlockpt\fR() +shall return 0. Otherwise, it shall return \-1 and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIunlockpt\fR() +function may fail if: +.TP +.BR EBADF +The +.IR fildes +argument is not a file descriptor open for writing. +.TP +.BR EINVAL +The +.IR fildes +argument is not associated with a master pseudo-terminal device. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See the RATIONALE section for +.IR "\fIposix_openpt\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgrantpt\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIposix_openpt\fR\^(\|)", +.IR "\fIptsname\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/unsetenv.3p b/upstream/archlinux/man3p/unsetenv.3p new file mode 100644 index 00000000..7ff84438 --- /dev/null +++ b/upstream/archlinux/man3p/unsetenv.3p @@ -0,0 +1,94 @@ +'\" et +.TH UNSETENV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +unsetenv +\(em remove an environment variable +.SH SYNOPSIS +.LP +.nf +#include +.P +int unsetenv(const char *\fIname\fP); +.fi +.SH DESCRIPTION +The +\fIunsetenv\fR() +function shall remove an environment variable from the environment +of the calling process. The +.IR name +argument points to a string, which is the name of the variable to be +removed. The named argument shall not contain an +.BR '=' +character. If the named variable does not exist in the current +environment, the environment shall be unchanged and the function is +considered to have completed successfully. +.P +The +\fIunsetenv\fR() +function shall update the list of pointers to which +.IR environ +points. +.P +The +\fIunsetenv\fR() +function need not be thread-safe. +.SH "RETURN VALUE" +Upon successful completion, zero shall be returned. Otherwise, \-1 +shall be returned, +.IR errno +set to indicate the error, and the environment shall be unchanged. +.SH ERRORS +The +\fIunsetenv\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR name +argument points to an empty string, or points to a +string containing an +.BR '=' +character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to the RATIONALE section in +.IR "\fIsetenv\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIgetenv\fR\^(\|)", +.IR "\fIsetenv\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/uselocale.3p b/upstream/archlinux/man3p/uselocale.3p new file mode 100644 index 00000000..89a8a93a --- /dev/null +++ b/upstream/archlinux/man3p/uselocale.3p @@ -0,0 +1,126 @@ +'\" et +.TH USELOCALE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +uselocale +\(em use locale in current thread +.SH SYNOPSIS +.LP +.nf +#include +.P +locale_t uselocale(locale_t \fInewloc\fP); +.fi +.SH DESCRIPTION +The +\fIuselocale\fR() +function shall set or query the current locale for the calling thread. +.P +The value for the +.IR newloc +argument shall be one of the following: +.IP " 1." 4 +A value returned by the +\fInewlocale\fR() +or +\fIduplocale\fR() +functions +.IP " 2." 4 +The special locale object descriptor LC_GLOBAL_LOCALE +.IP " 3." 4 +(\c +.BR locale_t )0 +.P +If the +.IR newloc +argument is (\c +.BR locale_t )0, +the current locale shall not be changed; this value can be used to +query the current locale setting. If the +.IR newloc +argument is LC_GLOBAL_LOCALE, any thread-local locale for the calling +thread shall be uninstalled; the thread shall again use the global +locale as the current locale, and changes to the global locale shall +affect the thread. Otherwise, the locale represented by +.IR newloc +shall be installed as a thread-local locale to be used as the current +locale for the calling thread. +.P +Once the +\fIuselocale\fR() +function has been called to install a thread-local locale, the +behavior of every interface using data from the current locale shall +be affected for the calling thread. The current locale for other +threads shall remain unchanged. +.SH "RETURN VALUE" +Upon successful completion, the +\fIuselocale\fR() +function shall return a handle for the thread-local locale that was in +use as the current locale for the calling thread on entry to the function, +or LC_GLOBAL_LOCALE if no thread-local locale was in use. Otherwise, +\fIuselocale\fR() +shall return (\c +.BR locale_t )0 +and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIuselocale\fR() +function may fail if: +.TP +.BR EINVAL +.IR newloc +is not a valid locale object and is not (\c +.BR locale_t )0. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Unlike the +\fIsetlocale\fR() +function, the +\fIuselocale\fR() +function does not allow replacing some locale categories +only. Applications that need to install a locale which differs only in +a few categories must use +\fInewlocale\fR() +to change a locale object equivalent to the currently used locale and +install it. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIduplocale\fR\^(\|)", +.IR "\fIfreelocale\fR\^(\|)", +.IR "\fInewlocale\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/utime.3p b/upstream/archlinux/man3p/utime.3p new file mode 100644 index 00000000..f9d6f30f --- /dev/null +++ b/upstream/archlinux/man3p/utime.3p @@ -0,0 +1,204 @@ +'\" et +.TH UTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +utime +\(em set file access and modification times +.SH SYNOPSIS +.LP +.nf +#include +.P +int utime(const char *\fIpath\fP, const struct utimbuf *\fItimes\fP); +.fi +.SH DESCRIPTION +The +\fIutime\fR() +function shall set the access and modification times of the file named +by the +.IR path +argument. +.P +If +.IR times +is a null pointer, the access and modification times of the file shall +be set to the current time. The effective user ID of the process shall +match the owner of the file, or the process has write permission to the +file or has appropriate privileges, to use +\fIutime\fR() +in this manner. +.P +If +.IR times +is not a null pointer, +.IR times +shall be interpreted as a pointer to a +.BR utimbuf +structure and the access and modification times shall be set to the +values contained in the designated structure. Only a process with +the effective user ID equal to the user ID of the file or a process with +appropriate privileges may use +\fIutime\fR() +this way. +.P +The +.BR utimbuf +structure is defined in the +.IR +header. The times in the structure +.BR utimbuf +are measured in seconds since the Epoch. +.P +Upon successful completion, the +\fIutime\fR() +function shall mark the last file status change timestamp +for update; see +.IR . +.SH "RETURN VALUE" +Upon successful completion, 0 shall be returned. Otherwise, \-1 +shall be returned and +.IR errno +shall be set to indicate the error, and the file times shall not be +affected. +.SH ERRORS +The +\fIutime\fR() +function shall fail if: +.TP +.BR EACCES +Search permission is denied by a component of the path prefix; or the +.IR times +argument is a null pointer and the effective user ID of the process +does not match the owner of the file, the process does not have write +permission for the file, and the process does not have appropriate +privileges. +.TP +.BR ELOOP +A loop exists in symbolic links encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a component of a pathname is longer than +{NAME_MAX}. +.TP +.BR ENOENT +A component of +.IR path +does not name an existing file or +.IR path +is an empty string. +.TP +.BR ENOTDIR +A component of the path prefix names an existing file that is neither +a directory nor a symbolic link to a directory, or the +.IR path +argument contains at least one non-\c + +character and ends with one or more trailing + +characters and the last pathname component names an existing file +that is neither a directory nor a symbolic link to a directory. +.TP +.BR EPERM +The +.IR times +argument is not a null pointer and the effective user ID of the calling +process does not match the owner of the file and the calling process +does not have appropriate privileges. +.TP +.BR EROFS +The file system containing the file is read-only. +.br +.P +The +\fIutime\fR() +function may fail if: +.TP +.BR ELOOP +More than +{SYMLOOP_MAX} +symbolic links were encountered during resolution of the +.IR path +argument. +.TP +.BR ENAMETOOLONG +.br +The length of a pathname exceeds +{PATH_MAX}, +or pathname resolution of a symbolic link produced an intermediate +result with a length that exceeds +{PATH_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Since the +.BR utimbuf +structure only contains +.BR time_t +variables and is not accurate to fractions of a second, +applications should use the +\fIutimensat\fR() +function instead of the obsolescent +\fIutime\fR() +function. +.SH RATIONALE +The +.IR actime +structure member must be present so that an application may set it, +even though an implementation may ignore it and not change the last data +access timestamp on the file. If an application intends to leave one of +the times of a file unchanged while changing the other, it should use +\fIstat\fR() +or +\fIfstat\fR() +to retrieve the file's +.IR st_atim +and +.IR st_mtim +parameters, set +.IR actime +and +.IR modtime +in the buffer, and change one of them before making the +\fIutime\fR() +call. +.SH "FUTURE DIRECTIONS" +The +\fIutime\fR() +function may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIfstat\fR\^(\|)", +.IR "\fIfstatat\fR\^(\|)", +.IR "\fIfutimens\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/utimensat.3p b/upstream/archlinux/man3p/utimensat.3p new file mode 100644 index 00000000..0f5e88a0 --- /dev/null +++ b/upstream/archlinux/man3p/utimensat.3p @@ -0,0 +1,45 @@ +'\" et +.TH UTIMENSAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +utimensat, utimes +\(em set file access and modification times +.SH SYNOPSIS +.LP +.nf +#include +.P +int utimensat(int \fIfd\fP, const char *\fIpath\fP, const struct timespec \fItimes\fP[2], + int \fIflag\fP); +.P +#include +.P +int utimes(const char *\fIpath\fP, const struct timeval \fItimes\fP[2]); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfutimens\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/va_arg.3p b/upstream/archlinux/man3p/va_arg.3p new file mode 100644 index 00000000..4a48b346 --- /dev/null +++ b/upstream/archlinux/man3p/va_arg.3p @@ -0,0 +1,46 @@ +'\" et +.TH VA_ARG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +va_arg, +va_copy, +va_end, +va_start +\(em handle variable argument list +.SH SYNOPSIS +.LP +.nf +#include +.P +\fItype\fP va_arg(va_list \fIap\fP, \fItype\fP); +void va_copy(va_list \fIdest\fP, va_list \fIsrc\fP); +void va_end(va_list \fIap\fP); +void va_start(va_list \fIap\fP, \fIargN\fP); +.fi +.SH DESCRIPTION +Refer to the Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vfprintf.3p b/upstream/archlinux/man3p/vfprintf.3p new file mode 100644 index 00000000..cf63c3c2 --- /dev/null +++ b/upstream/archlinux/man3p/vfprintf.3p @@ -0,0 +1,103 @@ +'\" et +.TH VFPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vdprintf, +vfprintf, +vprintf, +vsnprintf, +vsprintf +\(em format output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vdprintf(int \fIfildes\fR, const char *restrict \fIformat\fR, va_list \fIap\fR); +int vfprintf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, + va_list \fIap\fP); +int vprintf(const char *restrict \fIformat\fP, va_list \fIap\fP); +int vsnprintf(char *restrict \fIs\fP, size_t \fIn\fP, const char *restrict \fIformat\fP, + va_list \fIap\fP); +int vsprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, va_list \fIap\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIvdprintf\fR(), +\fIvfprintf\fR(), +\fIvprintf\fR(), +\fIvsnprintf\fR(), +and +\fIvsprintf\fR() +functions shall be equivalent to the \& +\fIdprintf\fR(), +\fIfprintf\fR(), +\fIprintf\fR(), +\fIsnprintf\fR(), +and +\fIsprintf\fR() +functions respectively, except that instead of being called with a +variable number of arguments, they are called with an argument list as +defined by +.IR . +.P +These functions shall not invoke the +.IR va_end +macro. As these functions invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfprintf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfprintf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call \fIva_end\fP(\fIap\fP) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vfscanf.3p b/upstream/archlinux/man3p/vfscanf.3p new file mode 100644 index 00000000..1f45d0f5 --- /dev/null +++ b/upstream/archlinux/man3p/vfscanf.3p @@ -0,0 +1,96 @@ +'\" et +.TH VFSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vfscanf, +vscanf, +vsscanf +\(em format input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vfscanf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, + va_list \fIarg\fP); +int vscanf(const char *restrict \fIformat\fP, va_list \fIarg\fP); +int vsscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, + va_list \fIarg\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIvscanf\fR(), +\fIvfscanf\fR(), +and +\fIvsscanf\fR() +functions shall be equivalent to the +\fIscanf\fR(), +\fIfscanf\fR(), +and +\fIsscanf\fR() +functions, respectively, except that instead of being called with a +variable number of arguments, they are called with an argument list as +defined in the +.IR +header. These functions shall not invoke the +.IR va_end +macro. As these functions invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfscanf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfscanf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call +.IR va_end (\c +.IR ap ) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfscanf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vfwprintf.3p b/upstream/archlinux/man3p/vfwprintf.3p new file mode 100644 index 00000000..8e4925e5 --- /dev/null +++ b/upstream/archlinux/man3p/vfwprintf.3p @@ -0,0 +1,97 @@ +'\" et +.TH VFWPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vfwprintf, +vswprintf, +vwprintf +\(em wide-character formatted output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vfwprintf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +int vswprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +int vwprintf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIvfwprintf\fR(), +\fIvswprintf\fR(), +and +\fIvwprintf\fR() +functions shall be equivalent to +\fIfwprintf\fR(), +\fIswprintf\fR(), +and +\fIwprintf\fR() +respectively, except that instead of being called with a variable +number of arguments, they are called with an argument list as defined +by +.IR . +.P +These functions shall not invoke the +.IR va_end +macro. However, as these functions do invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call \fIva_end\fP(\fIap\fP) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfwprintf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vfwscanf.3p b/upstream/archlinux/man3p/vfwscanf.3p new file mode 100644 index 00000000..d3711d5f --- /dev/null +++ b/upstream/archlinux/man3p/vfwscanf.3p @@ -0,0 +1,98 @@ +'\" et +.TH VFWSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vfwscanf, +vswscanf, +vwscanf +\(em wide-character formatted input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vfwscanf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +int vswscanf(const wchar_t *restrict \fIws\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +int vwscanf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIvfwscanf\fR(), +\fIvswscanf\fR(), +and +\fIvwscanf\fR() +functions shall be equivalent to the +\fIfwscanf\fR(), +\fIswscanf\fR(), +and +\fIwscanf\fR() +functions, respectively, except that instead of being called with a +variable number of arguments, they are called with an argument list as +defined in the +.IR +header. These functions shall not invoke the +.IR va_end +macro. As these functions invoke the +.IR va_arg +macro, the value of +.IR ap +after the return is unspecified. +.SH "RETURN VALUE" +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.SH ERRORS +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Applications using these functions should call +.IR va_end (\c +.IR ap ) +afterwards to clean up. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5" ", " "Standard I/O Streams", +.IR "\fIfwscanf\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vprintf.3p b/upstream/archlinux/man3p/vprintf.3p new file mode 100644 index 00000000..9f715940 --- /dev/null +++ b/upstream/archlinux/man3p/vprintf.3p @@ -0,0 +1,41 @@ +'\" et +.TH VPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vprintf +\(em format the output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vprintf(const char *restrict \fIformat\fP, va_list \fIap\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vscanf.3p b/upstream/archlinux/man3p/vscanf.3p new file mode 100644 index 00000000..b1828852 --- /dev/null +++ b/upstream/archlinux/man3p/vscanf.3p @@ -0,0 +1,41 @@ +'\" et +.TH VSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vscanf +\(em format input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vscanf(const char *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vsnprintf.3p b/upstream/archlinux/man3p/vsnprintf.3p new file mode 100644 index 00000000..3a5eee2b --- /dev/null +++ b/upstream/archlinux/man3p/vsnprintf.3p @@ -0,0 +1,45 @@ +'\" et +.TH VSNPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vsnprintf, +vsprintf +\(em format output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vsnprintf(char *restrict \fIs\fP, size_t \fIn\fP, + const char *restrict \fIformat\fP, va_list \fIap\fP); +int vsprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, + va_list \fIap\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vsscanf.3p b/upstream/archlinux/man3p/vsscanf.3p new file mode 100644 index 00000000..77557d07 --- /dev/null +++ b/upstream/archlinux/man3p/vsscanf.3p @@ -0,0 +1,42 @@ +'\" et +.TH VSSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vsscanf +\(em format input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int vsscanf(const char *restrict \fIs\fP, const char *restrict \fIformat\fP, + va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vswprintf.3p b/upstream/archlinux/man3p/vswprintf.3p new file mode 100644 index 00000000..83415580 --- /dev/null +++ b/upstream/archlinux/man3p/vswprintf.3p @@ -0,0 +1,43 @@ +'\" et +.TH VSWPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vswprintf +\(em wide-character formatted output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vswprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP, + const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vswscanf.3p b/upstream/archlinux/man3p/vswscanf.3p new file mode 100644 index 00000000..bd3bcb6d --- /dev/null +++ b/upstream/archlinux/man3p/vswscanf.3p @@ -0,0 +1,43 @@ +'\" et +.TH VSWSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vswscanf +\(em wide-character formatted input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vswscanf(const wchar_t *restrict \fIws\fP, const wchar_t *restrict \fIformat\fP, + va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vwprintf.3p b/upstream/archlinux/man3p/vwprintf.3p new file mode 100644 index 00000000..94c14199 --- /dev/null +++ b/upstream/archlinux/man3p/vwprintf.3p @@ -0,0 +1,42 @@ +'\" et +.TH VWPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vwprintf +\(em wide-character formatted output of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vwprintf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/vwscanf.3p b/upstream/archlinux/man3p/vwscanf.3p new file mode 100644 index 00000000..c711cb75 --- /dev/null +++ b/upstream/archlinux/man3p/vwscanf.3p @@ -0,0 +1,42 @@ +'\" et +.TH VWSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +vwscanf +\(em wide-character formatted input of a stdarg argument list +.SH SYNOPSIS +.LP +.nf +#include +#include +#include +.P +int vwscanf(const wchar_t *restrict \fIformat\fP, va_list \fIarg\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIvfwscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wait.3p b/upstream/archlinux/man3p/wait.3p new file mode 100644 index 00000000..7f18dac7 --- /dev/null +++ b/upstream/archlinux/man3p/wait.3p @@ -0,0 +1,909 @@ +'\" et +.TH WAIT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wait, +waitpid +\(em wait for a child process to stop or terminate +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t wait(int *\fIstat_loc\fP); +pid_t waitpid(pid_t \fIpid\fP, int *\fIstat_loc\fP, int \fIoptions\fP); +.fi +.SH DESCRIPTION +The +\fIwait\fR() +and +\fIwaitpid\fR() +functions shall obtain status information (see +.IR "Section 2.13" ", " "Status Information") +pertaining to one of the caller's child processes. The +\fIwait\fR() +function obtains status information for process termination from +any child process. The +\fIwaitpid\fR() +function obtains status information for process termination, and +optionally process stop and/or continue, from a specified subset of +the child processes. +.P +The +\fIwait\fR() +function shall cause the calling thread to become blocked until status +information generated by child process termination is made available +to the thread, or until delivery of a signal whose action is either to +execute a signal-catching function or to terminate the process, or an +error occurs. If termination status information is available prior to +the call to +\fIwait\fR(), +return shall be immediate. If termination status information is +available for two or more child processes, the order in which their +status is reported is unspecified. +.P +As described in +.IR "Section 2.13" ", " "Status Information", +the +\fIwait\fR() +and +\fIwaitpid\fR() +functions consume the status information they obtain. +.P +The behavior when multiple threads are blocked in +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +is described in +.IR "Section 2.13" ", " "Status Information". +.P +The +\fIwaitpid\fR() +function shall be equivalent to +\fIwait\fR() +if the +.IR pid +argument is (\fBpid_t\fP)\-1 and the +.IR options +argument is 0. Otherwise, its behavior shall be modified by the values +of the +.IR pid +and +.IR options +arguments. +.P +The +.IR pid +argument specifies a set of child processes for which +.IR status +is requested. The +\fIwaitpid\fR() +function shall only return the status of a child process from this set: +.IP " *" 4 +If +.IR pid +is equal to (\fBpid_t\fP)\-1, +.IR status +is requested for any child process. In this respect, +\fIwaitpid\fR() +is then equivalent to +\fIwait\fR(). +.IP " *" 4 +If +.IR pid +is greater than 0, it specifies the process ID of a single child +process for which +.IR status +is requested. +.IP " *" 4 +If +.IR pid +is 0, +.IR status +is requested for any child process whose process group ID is equal to +that of the calling process. +.IP " *" 4 +If +.IR pid +is less than (\fBpid_t\fP)\-1, +.IR status +is requested for any child process whose process group ID is equal to +the absolute value of +.IR pid . +.P +The +.IR options +argument is constructed from the bitwise-inclusive OR of zero or more +of the following flags, defined in the +.IR +header: +.IP WCONTINUED 12 +The +\fIwaitpid\fR() +function shall report the status of any continued child process +specified by +.IR pid +whose status has not been reported since it continued from a job +control stop. +.IP WNOHANG 12 +The +\fIwaitpid\fR() +function shall not suspend execution of the calling thread if +.IR status +is not immediately available for one of the child processes specified +by +.IR pid . +.IP WUNTRACED 12 +The status of any child processes specified by +.IR pid +that are stopped, and whose status has not yet been reported since they +stopped, shall also be reported to the requesting process. +.P +If +\fIwait\fR() +or +\fIwaitpid\fR() +return because the status of a child process is available, these +functions shall return a value equal to the process ID of the child +process. In this case, if the value of the argument +.IR stat_loc +is not a null pointer, information shall be stored in the location +pointed to by +.IR stat_loc . +The value stored at the location pointed to by +.IR stat_loc +shall be 0 if and only if the status returned is from a terminated +child process that terminated by one of the following means: +.IP " 1." 4 +The process returned 0 from +\fImain\fR(). +.IP " 2." 4 +The process called +\fI_exit\fR() +or +\fIexit\fR() +with a +.IR status +argument of 0. +.IP " 3." 4 +The process was terminated because the last thread in the process +terminated. +.P +Regardless of its value, this information may be +interpreted using the following macros, which are defined in +.IR +and evaluate to integral expressions; the +.IR stat_val +argument is the integer value pointed to by +.IR stat_loc . +.IP "WIFEXITED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that terminated normally. +.IP "WEXITSTATUS(\fIstat_val\fP)" 6 +.br +If the value of WIFEXITED(\fIstat_val\fP) is non-zero, this macro +evaluates to the low-order 8 bits of the +.IR status +argument that the child process passed to +\fI_exit\fR() +or +\fIexit\fR(), +or the value the child process returned from +\fImain\fR(). +.IP "WIFSIGNALED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that terminated due to the receipt of +a signal that was not caught (see +.IR ). +.IP "WTERMSIG(\fIstat_val\fP)" 6 +.br +If the value of WIFSIGNALED(\fIstat_val\fP) is non-zero, this macro +evaluates to the number of the signal that caused the termination of +the child process. +.IP "WIFSTOPPED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that is currently stopped. +.IP "WSTOPSIG(\fIstat_val\fP)" 6 +.br +If the value of WIFSTOPPED(\fIstat_val\fP) is non-zero, this macro +evaluates to the number of the signal that caused the child process to +stop. +.IP "WIFCONTINUED(\fIstat_val\fP)" 6 +.br +Evaluates to a non-zero value if +.IR status +was returned for a child process that has continued from a job control +stop. +.P +It is unspecified whether the +.IR status +value returned by calls to +\fIwait\fR() +or +\fIwaitpid\fR() +for processes created by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +can indicate a WIFSTOPPED(\fIstat_val\fP) before subsequent calls to +\fIwait\fR() +or +\fIwaitpid\fR() +indicate WIFEXITED(\fIstat_val\fP) as the result of an error detected +before the new process image starts executing. +.P +It is unspecified whether the +.IR status +value returned by calls to +\fIwait\fR() +or +\fIwaitpid\fR() +for processes created by +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +can indicate a WIFSIGNALED(\fIstat_val\fP) if a signal is sent to the +parent's process group after +\fIposix_spawn\fR() +or +\fIposix_spawnp\fR() +is called. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that specified the WUNTRACED flag +and did not specify the WCONTINUED flag, +exactly one of the macros WIFEXITED(*\fIstat_loc\fR), +WIFSIGNALED(*\fIstat_loc\fR), and WIFSTOPPED(*\fIstat_loc\fR) +shall evaluate to a non-zero value. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that specified the WUNTRACED and WCONTINUED flags, exactly one +of the macros WIFEXITED(*\fIstat_loc\fR), +WIFSIGNALED(*\fIstat_loc\fR), WIFSTOPPED(*\fIstat_loc\fR), +and WIFCONTINUED(*\fIstat_loc\fR) shall evaluate to a non-zero value. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that did not specify the WUNTRACED +or WCONTINUED +flags, or by a call to the +\fIwait\fR() +function, exactly one of the macros WIFEXITED(*\fIstat_loc\fR) and +WIFSIGNALED(*\fIstat_loc\fR) shall evaluate to a non-zero value. +.P +If the information pointed to by +.IR stat_loc +was stored by a call to +\fIwaitpid\fR() +that did not specify the WUNTRACED flag and specified the WCONTINUED flag, +exactly one of the macros WIFEXITED(*\fIstat_loc\fR), +WIFSIGNALED(*\fIstat_loc\fR), and WIFCONTINUED(*\fIstat_loc\fR) +shall evaluate to a non-zero value. +.P +If _POSIX_REALTIME_SIGNALS is defined, and the implementation queues +the SIGCHLD signal, then if +\fIwait\fR() +or +\fIwaitpid\fR() +returns because the status of a child process is available, any pending +SIGCHLD signal associated with the process ID of the child process +shall be discarded. Any other pending SIGCHLD signals shall remain +pending. +.P +Otherwise, if SIGCHLD is blocked, if +\fIwait\fR() +or +\fIwaitpid\fR() +return because the status of a child process is available, any pending +SIGCHLD signal shall be cleared unless the status of another child +process is available. +.P +For all other conditions, it is unspecified whether child +.IR status +will be available when a SIGCHLD signal is delivered. +.P +There may be additional implementation-defined circumstances under +which +\fIwait\fR() +or +\fIwaitpid\fR() +report +.IR status . +This shall not occur unless the calling process or one of its child +processes explicitly makes use of a non-standard extension. In these +cases the interpretation of the reported +.IR status +is implementation-defined. +.P +If a parent process terminates without waiting for all of its child +processes to terminate, the remaining child processes shall be assigned +a new parent process ID corresponding to an implementation-defined +system process. +.SH "RETURN VALUE" +If +\fIwait\fR() +or +\fIwaitpid\fR() +returns because the status of a child process is available, these +functions shall return a value equal to the process ID of the child +process for which +.IR status +is reported. If +\fIwait\fR() +or +\fIwaitpid\fR() +returns due to the delivery of a signal to the calling process, \-1 +shall be returned and +.IR errno +set to +.BR [EINTR] . +If +\fIwaitpid\fR() +was invoked with WNOHANG set in +.IR options , +it has at least one child process specified by +.IR pid +for which +.IR status +is not available, and +.IR status +is not available for any process specified by +.IR pid , +0 is returned. Otherwise, \-1 shall be returned, and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIwait\fR() +function shall fail if: +.TP +.BR ECHILD +The calling process has no existing unwaited-for child processes. +.TP +.BR EINTR +The function was interrupted by a signal. The value of the location +pointed to by +.IR stat_loc +is undefined. +.P +The +\fIwaitpid\fR() +function shall fail if: +.TP +.BR ECHILD +The process specified by +.IR pid +does not exist or is not a child of the calling process, or the process +group specified by +.IR pid +does not exist or does not have any member process that is a child of +the calling process. +.TP +.BR EINTR +The function was interrupted by a signal. The value of the location +pointed to by +.IR stat_loc +is undefined. +.TP +.BR EINVAL +The +.IR options +argument is not valid. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Waiting for a Child Process and then Checking its Status" +.P +The following example demonstrates the use of +\fIwaitpid\fR(), +\fIfork\fR(), +and the macros used to interpret the status value returned by +\fIwaitpid\fR() +(and +\fIwait\fR()). +The code segment creates a child process which does some unspecified +work. Meanwhile the parent loops performing calls to +\fIwaitpid\fR() +to monitor the status of the child. The loop terminates when child +termination is detected. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +\&... +.P +pid_t child_pid, wpid; +int status; +.P +child_pid = fork(); +if (child_pid == -1) { /* fork() failed */ + perror("fork"); + exit(EXIT_FAILURE); +} +.P +if (child_pid == 0) { /* This is the child */ + /* Child does some work and then terminates */ + ... +.P +} else { /* This is the parent */ + do { + wpid = waitpid(child_pid, &status, WUNTRACED +#ifdef WCONTINUED /* Not all implementations support this */ + | WCONTINUED +#endif + ); + if (wpid == -1) { + perror("waitpid"); + exit(EXIT_FAILURE); + } +.P + if (WIFEXITED(status)) { + printf("child exited, status=%d\en", WEXITSTATUS(status)); +.P + } else if (WIFSIGNALED(status)) { + printf("child killed (signal %d)\en", WTERMSIG(status)); +.P + } else if (WIFSTOPPED(status)) { + printf("child stopped (signal %d)\en", WSTOPSIG(status)); +.P +#ifdef WIFCONTINUED /* Not all implementations support this */ + } else if (WIFCONTINUED(status)) { + printf("child continued\en"); +#endif + } else { /* Non-standard case -- may never happen */ + printf("Unexpected status (0x%x)\en", status); + } + } while (!WIFEXITED(status) && !WIFSIGNALED(status)); +} +.fi +.P +.RE +.SS "Waiting for a Child Process in a Signal Handler for SIGCHLD" +.P +The following example demonstrates how to use +\fIwaitpid\fR() +in a signal handler for SIGCHLD without passing \-1 as the +.IR pid +argument. (See the APPLICATION USAGE section below for the reasons +why passing a +.IR pid +of \-1 is not recommended.) The method used here relies on the +standard behavior of +\fIwaitpid\fR() +when SIGCHLD is blocked. On historical non-conforming systems, the +status of some child processes might not be reported. +.sp +.RS 4 +.nf + +#include +#include +#include +#include +#include +#include +.P +#define CHILDREN 10 +.P +static void +handle_sigchld(int signum, siginfo_t *sinfo, void *unused) +{ + int sav_errno = errno; + int status; +.P + /* + * Obtain status information for the child which + * caused the SIGCHLD signal and write its exit code + * to stdout. + */ + if (sinfo->si_code != CLD_EXITED) + { + static char msg[] = "wrong si_code\en"; + write(2, msg, sizeof msg - 1); + } + else if (waitpid(sinfo->si_pid, &status, 0) =\|= -1) + { + static char msg[] = "waitpid() failed\en"; + write(2, msg, sizeof msg - 1); + } + else if (!WIFEXITED(status)) + { + static char msg[] = "WIFEXITED was false\en"; + write(2, msg, sizeof msg - 1); + } + else + { + int code = WEXITSTATUS(status); + char buf[2]; + buf[0] = \(aq0\(aq + code; + buf[1] = \(aq\en\(aq; + write(1, buf, 2); + } + errno = sav_errno; +} +.P +int +main(void) +{ + int i; + pid_t pid; + struct sigaction sa; +.P + sa.sa_flags = SA_SIGINFO; + sa.sa_sigaction = handle_sigchld; + sigemptyset(&sa.sa_mask); + if (sigaction(SIGCHLD, &sa, NULL) =\|= -1) + { + perror("sigaction"); + exit(EXIT_FAILURE); + } +.P + for (i = 0; i < CHILDREN; i++) + { + switch (pid = fork()) + { + case -1: + perror("fork"); + exit(EXIT_FAILURE); + case 0: + sleep(2); + _exit(i); + } + } +.P + /* Wait for all the SIGCHLD signals, then terminate on SIGALRM */ + alarm(3); + for (;;) + pause(); +.P + return 0; /* NOTREACHED */ +} +.fi +.P +.RE +.SH "APPLICATION USAGE" +Calls to +\fIwait\fR() +will collect information about any child process. This may result in +interactions with other interfaces that may be waiting for their own +children (such as by use of +\fIsystem\fR()). +For this and other reasons it is recommended that portable applications +not use +\fIwait\fR(), +but instead use +\fIwaitpid\fR(). +For these same reasons, the use of +\fIwaitpid\fR() +with a +.IR pid +argument of \-1, and the use of +\fIwaitid\fR() +with the +.IR idtype +argument set to P_ALL, are also not recommended for portable applications. +.P +As specified in +.IR "Consequences of Process Termination", +if the calling process has SA_NOCLDWAIT set or has SIGCHLD set to +SIG_IGN, then the termination of a child process will not cause status +information to become available to a thread blocked in +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(). +Thus, a thread blocked in one of the wait functions will remain +blocked unless some other condition causes the thread to resume +execution (such as an +.BR [ECHILD] +failure due to no remaining children in the set of waited-for children). +.SH RATIONALE +A call to the +\fIwait\fR() +or +\fIwaitpid\fR() +function only returns +.IR status +on an immediate child process of the calling process; that is, a child +that was produced by a single +\fIfork\fR() +call (perhaps followed by an +.IR exec +or other function calls) from the parent. If a child produces +grandchildren by further use of +\fIfork\fR(), +none of those grandchildren nor any of their descendants affect the +behavior of a +\fIwait\fR() +from the original parent process. Nothing in this volume of POSIX.1\(hy2017 prevents an +implementation from providing extensions that permit a process to get +.IR status +from a grandchild or any other process, but a process that does not use +such extensions must be guaranteed to see +.IR status +from only its direct children. +.P +The +\fIwaitpid\fR() +function is provided for three reasons: +.IP " 1." 4 +To support job control +.IP " 2." 4 +To permit a non-blocking version of the +\fIwait\fR() +function +.IP " 3." 4 +To permit a library routine, such as +\fIsystem\fR() +or +\fIpclose\fR(), +to wait for its children without interfering with other terminated +children for which the process has not waited +.P +The first two of these facilities are based on the +.IR wait3 (\|) +function provided by 4.3 BSD. The function uses the +.IR options +argument, which is equivalent to an argument to +.IR wait3 (\|). +The WUNTRACED +flag is used only in conjunction with job control on systems supporting +job control. Its name comes from 4.3 BSD +and refers to the fact that there are two types of stopped processes in +that implementation: processes being traced via the +\fIptrace\fR() +debugging facility and (untraced) processes stopped by job control +signals. Since +\fIptrace\fR() +is not part of this volume of POSIX.1\(hy2017, only the second type is relevant. The name +WUNTRACED was retained because its usage is the same, even though the +name is not intuitively meaningful in this context. +.P +The third reason for the +\fIwaitpid\fR() +function is to permit independent sections of a process to spawn and +wait for children without interfering with each other. For example, +the following problem occurs in developing a portable shell, or command +interpreter: +.sp +.RS 4 +.nf + +stream = popen("/bin/true"); +(void) system("sleep 100"); +(void) pclose(stream); +.fi +.P +.RE +.P +On all historical implementations, the final +\fIpclose\fR() +fails to reap the +\fIwait\fR() +.IR status +of the +\fIpopen\fR(). +.P +The status values are retrieved by macros, rather than given as +specific bit encodings as they are in most historical implementations +(and thus expected by existing programs). This was necessary to +eliminate a limitation on the number of signals an implementation can +support that was inherent in the traditional encodings. This volume of POSIX.1\(hy2017 +does require that a +.IR status +value of zero corresponds to a process calling +.IR _exit (0), +as this is the most common encoding expected by existing programs. +Some of the macro names were adopted from 4.3 BSD. +.P +These macros syntactically operate on an arbitrary integer value. The +behavior is undefined unless that value is one stored by a successful +call to +\fIwait\fR() +or +\fIwaitpid\fR() +in the location pointed to by the +.IR stat_loc +argument. An early proposal attempted to make this clearer by specifying +each argument as *\fIstat_loc\fP rather than +.IR stat_val . +However, that did not follow the conventions of other specifications in +\&this volume of POSIX.1\(hy2017 or traditional usage. It also could have implied that the +argument to the macro must literally be *\fIstat_loc\fP; in fact, that +value can be stored or passed as an argument to other functions before +being interpreted by these macros. +.P +The extension that affects +\fIwait\fR() +and +\fIwaitpid\fR() +and is common in historical implementations is the +\fIptrace\fR() +function. It is called by a child process and causes that child to +stop and return a +.IR status +that appears identical to the +.IR status +indicated by WIFSTOPPED. +The +.IR status +of +\fIptrace\fR() +children is traditionally returned regardless of the WUNTRACED +flag (or by the +\fIwait\fR() +function). Most applications do not need to concern themselves with +such extensions because they have control over what extensions they or +their children use. However, applications, such as command +interpreters, that invoke arbitrary processes may see this behavior +when those arbitrary processes misuse such extensions. +.P +Implementations that support +.BR core +file creation or other implementation-defined actions on termination +of some processes traditionally provide a bit in the +.IR status +returned by +\fIwait\fR() +to indicate that such actions have occurred. +.P +Allowing the +\fIwait\fR() +family of functions to discard a pending SIGCHLD signal that is +associated with a successfully waited-for child process puts them into +the +\fIsigwait\fR() +and +\fIsigwaitinfo\fR() +category with respect to SIGCHLD. +.P +This definition allows implementations to treat a pending SIGCHLD +signal as accepted by the process in +\fIwait\fR(), +with the same meaning of ``accepted'' as when that word is applied to +the +\fIsigwait\fR() +family of functions. +.P +Allowing the +\fIwait\fR() +family of functions to behave this way permits an implementation to be +able to deal precisely with SIGCHLD signals. +.P +In particular, an implementation that does accept (discard) the SIGCHLD +signal can make the following guarantees regardless of the queuing +depth of signals in general (the list of waitable children can hold the +SIGCHLD queue): +.IP " 1." 4 +If a SIGCHLD signal handler is established via +\fIsigaction\fR() +without the SA_RESETHAND flag, SIGCHLD signals can be accurately +counted; that is, exactly one SIGCHLD signal will be delivered to or +accepted by the process for every child process that terminates. +.IP " 2." 4 +A single +\fIwait\fR() +issued from a SIGCHLD signal handler can be guaranteed to return +immediately with status information for a child process. +.IP " 3." 4 +When SA_SIGINFO is requested, the SIGCHLD signal handler can be +guaranteed to receive a non-null pointer to a +.BR siginfo_t +structure that describes a child process for which a wait via +\fIwaitpid\fR() +or +\fIwaitid\fR() +will not block or fail. +.IP " 4." 4 +The +\fIsystem\fR() +function will not cause the SIGCHLD handler of a process to be +called as a result of the +\fIfork\fR()/\c +.IR exec +executed within +\fIsystem\fR() +because +\fIsystem\fR() +will accept the SIGCHLD signal when it performs a +\fIwaitpid\fR() +for its child process. This is a desirable behavior of +\fIsystem\fR() +so that it can be used in a library without causing side-effects to the +application linked with the library. +.P +An implementation that does not permit the +\fIwait\fR() +family of functions to accept (discard) a pending SIGCHLD signal +associated with a successfully waited-for child, cannot make the +guarantees described above for the following reasons: +.IP "Guarantee #1" 6 +.br +Although it might be assumed that reliable queuing of all SIGCHLD +signals generated by the system can make this guarantee, the +counter-example is the case of a process that blocks SIGCHLD and +performs an indefinite loop of +\fIfork\fR()/\c +\fIwait\fR() +operations. If the implementation supports queued signals, then +eventually the system will run out of memory for the queue. The +guarantee cannot be made because there must be some limit to the depth +of queuing. +.IP "Guarantees #2 and #3" 6 +.br +These cannot be guaranteed unless the +\fIwait\fR() +family of functions accepts the SIGCHLD signal. Otherwise, a +\fIfork\fR()/\c +\fIwait\fR() +executed while SIGCHLD is blocked (as in the +\fIsystem\fR() +function) will result in an invocation of the handler when SIGCHLD is +unblocked, after the process has disappeared. +.IP "Guarantee #4" 6 +.br +Although possible to make this guarantee, +\fIsystem\fR() +would have to set the SIGCHLD handler to SIG_DFL so that the SIGCHLD +signal generated by its +\fIfork\fR() +would be discarded (the SIGCHLD default action is to be ignored), then +restore it to its previous setting. This would have the undesirable +side-effect of discarding all SIGCHLD signals pending to the process. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.13" ", " "Status Information", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIfork\fR\^(\|)", +.IR "\fIsystem\fR\^(\|)", +.IR "\fIwaitid\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.12" ", " "Memory Synchronization", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/waitid.3p b/upstream/archlinux/man3p/waitid.3p new file mode 100644 index 00000000..43f7c692 --- /dev/null +++ b/upstream/archlinux/man3p/waitid.3p @@ -0,0 +1,269 @@ +'\" et +.TH WAITID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +waitid +\(em wait for a child process to change state +.SH SYNOPSIS +.LP +.nf +#include +.P +int waitid(idtype_t \fIidtype\fP, id_t \fIid\fP, siginfo_t *\fIinfop\fP, int \fIoptions\fP); +.fi +.SH DESCRIPTION +The +\fIwaitid\fR() +function shall obtain status information (see +.IR "Section 2.13" ", " "Status Information") +pertaining to termination, stop, and/or continue events in one of the +caller's child processes. +.P +The +\fIwaitid\fR() +function shall cause the calling thread to become blocked until an +error occurs or status information becomes available to the calling +thread that satisfies all of the following properties (``matching status +information''): +.IP " *" 4 +The status information is from one of the child processes in the set +of child processes specified by the +.IR idtype +and +.IR id +arguments. +.IP " *" 4 +The state change in the status information matches one of the state +change flags set in the +.IR options +argument. +.P +If matching status information is available prior to the call to +\fIwaitid\fR(), +return shall be immediate. If matching status information is available +for two or more child processes, the order in which their status is +reported is unspecified. +.P +As described in +.IR "Section 2.13" ", " "Status Information", +the +\fIwaitid\fR() +function consumes the status information it obtains unless the +WNOWAIT flag is set in the +.IR options +argument. +.P +The behavior when multiple threads are blocked in +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR() +is described in +.IR "Section 2.13" ", " "Status Information". +.P +The +\fIwaitid\fR() +function shall record the obtained status information in the structure +pointed to by +.IR infop . +The fields of the structure pointed to by +.IR infop +shall be filled in as described under ``Pointer to a Function'' in +.IR "Section 2.4.3" ", " "Signal Actions". +.P +The +.IR idtype +and +.IR id +arguments are used to specify which children +\fIwaitid\fR() +waits for. +.P +If +.IR idtype +is P_PID, +\fIwaitid\fR() +shall wait for the child with a process ID equal to +(\fBpid_t\fP)\fIid\fR. +.P +If +.IR idtype +is P_PGID, +\fIwaitid\fR() +shall wait for any child with a process group ID equal to +(\fBpid_t\fP)\fIid\fR. +.P +If +.IR idtype +is P_ALL, +\fIwaitid\fR() +shall wait for any children and +.IR id +is ignored. +.P +The +.IR options +argument is used to specify which state changes +\fIwaitid\fR() +shall wait for. It is formed by OR'ing together the following flags: +.IP WCONTINUED 12 +Status shall be returned for any continued child process whose status +either has not been reported since it continued from a job control stop +or has been reported only by calls to +\fIwaitid\fR() +with the WNOWAIT flag set. +.IP WEXITED 12 +Wait for processes that have exited. +.IP WNOHANG 12 +Do not hang if no status is available; return immediately. +.IP WNOWAIT 12 +Keep the process whose status is returned in +.IR infop +in a waitable state. This shall not affect the state of the process; the +process may be waited for again after this call completes. +.IP WSTOPPED 12 +Status shall be returned for any child that has stopped upon receipt of +a signal, and whose status either has not been reported since it stopped +or has been reported only by calls to +\fIwaitid\fR() +with the WNOWAIT flag set. +.P +Applications shall specify at least one of the flags WEXITED, WSTOPPED, +or WCONTINUED to be OR'ed in with the +.IR options +argument. +.P +The application shall ensure that the +.IR infop +argument points to a +.BR siginfo_t +structure. If +\fIwaitid\fR() +returns because a child process was found that satisfied the conditions +indicated by the arguments +.IR idtype +and +.IR options , +then the structure pointed to by +.IR infop +shall be filled in by the system with the status of the process; the +.IR si_signo +member shall be set equal to SIGCHLD. +If +\fIwaitid\fR() +returns because WNOHANG was specified and status is not available for +any process specified by +.IR idtype +and +.IR id , +then the +.IR si_signo +and +.IR si_pid +members of the structure pointed to by +.IR infop +shall be set to zero and the values of other members of the structure +are unspecified. +.SH "RETURN VALUE" +If WNOHANG was specified and status is not available for any process +specified by +.IR idtype +and +.IR id , +0 shall be returned. If +\fIwaitid\fR() +returns due to the change of state of one of its children, 0 shall be +returned. Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +The +\fIwaitid\fR() +function shall fail if: +.TP +.BR ECHILD +The calling process has no existing unwaited-for child processes. +.TP +.BR EINTR +The +\fIwaitid\fR() +function was interrupted by a signal. +.TP +.BR EINVAL +An invalid value was specified for +.IR options , +or +.IR idtype +and +.IR id +specify an invalid set of processes. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Calls to +\fIwaitid\fR() +with +.IR idtype +equal to P_ALL will collect information about any child process. This +may result in interactions with other interfaces that may be waiting +for their own children (such as by use of +\fIsystem\fR()). +For this reason it is recommended that portable applications not use +\fIwaitid\fR() +with idtype of P_ALL. See also APPLICATION USAGE for +\fIwait\fR(). +.P +As specified in +.IR "Consequences of Process Termination", +if the calling process has SA_NOCLDWAIT set or has SIGCHLD set to +SIG_IGN, then the termination of a child process will not cause status +information to become available to a thread blocked in +\fIwait\fR(), +\fIwaitid\fR(), +or +\fIwaitpid\fR(). +Thus, a thread blocked in one of the wait functions will remain +blocked unless some other condition causes the thread to resume +execution (such as an +.BR [ECHILD] +failure due to no remaining children in the set of waited-for children). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.4.3" ", " "Signal Actions", +.IR "Section 2.13" ", " "Status Information", +.IR "\fIexec\fR\^", +.IR "\fIexit\fR\^(\|)", +.IR "\fIwait\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/waitpid.3p b/upstream/archlinux/man3p/waitpid.3p new file mode 100644 index 00000000..c34f344f --- /dev/null +++ b/upstream/archlinux/man3p/waitpid.3p @@ -0,0 +1,40 @@ +'\" et +.TH WAITPID "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +waitpid +\(em wait for a child process to stop or terminate +.SH SYNOPSIS +.LP +.nf +#include +.P +pid_t waitpid(pid_t \fIpid\fP, int *\fIstat_loc\fP, int \fIoptions\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwait\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcpcpy.3p b/upstream/archlinux/man3p/wcpcpy.3p new file mode 100644 index 00000000..a208276b --- /dev/null +++ b/upstream/archlinux/man3p/wcpcpy.3p @@ -0,0 +1,40 @@ +'\" et +.TH WCPCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcpcpy +\(em copy a wide-character string, returning a pointer to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpcpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcscpy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcpncpy.3p b/upstream/archlinux/man3p/wcpncpy.3p new file mode 100644 index 00000000..0b6df458 --- /dev/null +++ b/upstream/archlinux/man3p/wcpncpy.3p @@ -0,0 +1,42 @@ +'\" et +.TH WCPNCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcpncpy +\(em copy a fixed-size wide-character string, returning a pointer +to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpncpy(wchar_t restrict *\fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcsncpy\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcrtomb.3p b/upstream/archlinux/man3p/wcrtomb.3p new file mode 100644 index 00000000..3dd9551c --- /dev/null +++ b/upstream/archlinux/man3p/wcrtomb.3p @@ -0,0 +1,153 @@ +'\" et +.TH WCRTOMB "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcrtomb +\(em convert a wide-character code to a character (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcrtomb(char *restrict \fIs\fP, wchar_t \fIwc\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +If +.IR s +is a null pointer, the +\fIwcrtomb\fR() +function shall be equivalent to the call: +.sp +.RS 4 +.nf + +wcrtomb(\fIbuf\fP, L\(aq\e0\(aq, \fIps\fP) +.fi +.P +.RE +.P +where +.IR buf +is an internal buffer. +.P +If +.IR s +is not a null pointer, the +\fIwcrtomb\fR() +function shall determine the number of bytes needed to represent the +character that corresponds to the wide character given by +.IR wc +(including any shift sequences), and store the resulting bytes in the +array whose first element is pointed to by +.IR s . +At most +{MB_CUR_MAX} +bytes are stored. If +.IR wc +is a null wide character, a null byte shall be stored, preceded by any +shift sequence needed to restore the initial shift state. The resulting +state described shall be the initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fIwcrtomb\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. The implementation shall behave as +if no function defined in this volume of POSIX.1\(hy2017 calls +\fIwcrtomb\fR(). +.P +The +\fIwcrtomb\fR() +function need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +The +\fIwcrtomb\fR() +function shall not change the setting of +.IR errno +if successful. +.SH "RETURN VALUE" +The +\fIwcrtomb\fR() +function shall return the number of bytes stored in the array object +(including any shift sequences). When +.IR wc +is not a valid wide character, an encoding error shall occur. In this +case, the function shall store the value of the macro +.BR [EILSEQ] +in +.IR errno +and shall return (\fBsize_t\fP)\-1; the conversion state shall be +undefined. +.SH ERRORS +The +\fIwcrtomb\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid wide-character code is detected. +.P +The +\fIwcrtomb\fR() +function may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fIwcsrtombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcscasecmp.3p b/upstream/archlinux/man3p/wcscasecmp.3p new file mode 100644 index 00000000..2ed9f960 --- /dev/null +++ b/upstream/archlinux/man3p/wcscasecmp.3p @@ -0,0 +1,160 @@ +'\" et +.TH WCSCASECMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcscasecmp, +wcscasecmp_l, +wcsncasecmp, +wcsncasecmp_l +\(em case-insensitive wide-character string comparison +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcscasecmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +int wcscasecmp_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + locale_t \fIlocale\fP); +int wcsncasecmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +int wcsncasecmp_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +The +\fIwcscasecmp\fR() +and +\fIwcsncasecmp\fR() +functions are the wide-character equivalent of the +\fIstrcasecmp\fR() +and +\fIstrncasecmp\fR() +functions, respectively. +.P +The +\fIwcscasecmp\fR() +and +\fIwcscasecmp_l\fR() +functions shall compare, while ignoring differences in case, the +wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 . +.P +The +\fIwcsncasecmp\fR() +and +\fIwcsncasecmp_l\fR() +functions shall compare, while ignoring differences in case, not more +than +.IR n +wide-characters from the wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 . +.P +The +\fIwcscasecmp\fR() +and +\fIwcsncasecmp\fR() +functions use the current locale to determine the case of the wide +characters. +.P +The +\fIwcscasecmp_l\fR() +and +\fIwcsncasecmp_l\fR() +functions use the locale represented by +.IR locale +to determine the case of the wide characters. +.P +When the +.IR LC_CTYPE +category of the locale being used is from the POSIX locale, these +functions shall behave as if the wide-character strings had been converted +to lowercase and then a comparison of wide-character codes performed. +Otherwise, the results are unspecified. +.P +The information for +\fIwcscasecmp_l\fR() +and +\fIwcsncasecmp_l\fR() +about the case of the characters comes from the locale represented by +.IR locale . +.P +The behavior is undefined if the +.IR locale +argument to +\fIwcscasecmp_l\fR() +or +\fIwcsncasecmp_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon completion, the +\fIwcscasecmp\fR() +and +\fIwcscasecmp_l\fR() +functions shall return an integer greater than, equal to, or less than 0 +if the wide-character string pointed to by +.IR ws1 +is, ignoring case, greater than, equal to, or less than the +wide-character string pointed to by +.IR ws2 , +respectively. +.P +Upon completion, the +\fIwcsncasecmp\fR() +and +\fIwcsncasecmp_l\fR() +functions shall return an integer greater than, equal to, or less than 0 +if the possibly null wide-character terminated string pointed to by +.IR ws1 +is, ignoring case, greater than, equal to, or less than the possibly +null wide-character terminated string pointed to by +.IR ws2 , +respectively. +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcasecmp\fR\^(\|)", +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcsncmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcscat.3p b/upstream/archlinux/man3p/wcscat.3p new file mode 100644 index 00000000..18984db0 --- /dev/null +++ b/upstream/archlinux/man3p/wcscat.3p @@ -0,0 +1,78 @@ +'\" et +.TH WCSCAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcscat +\(em concatenate two wide-character strings +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcscat(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcscat\fR() +function shall append a copy of the wide-character string pointed to by +.IR ws2 +(including the terminating null wide-character code) to the end of the +wide-character string pointed to by +.IR ws1 . +The initial wide-character code of +.IR ws2 +shall overwrite the null wide-character code at the end of +.IR ws1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIwcscat\fR() +function shall return +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcsncat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcschr.3p b/upstream/archlinux/man3p/wcschr.3p new file mode 100644 index 00000000..42a1595f --- /dev/null +++ b/upstream/archlinux/man3p/wcschr.3p @@ -0,0 +1,77 @@ +'\" et +.TH WCSCHR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcschr +\(em wide-character string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcschr(const wchar_t *\fIws\fP, wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcschr\fR() +function shall locate the first occurrence of +.IR wc +in the wide-character string pointed to by +.IR ws . +The application shall ensure that the value of +.IR wc +is a character representable as a type +.BR wchar_t +and a wide-character code corresponding to a valid character in the +current locale. The terminating null wide-character code is considered +to be part of the wide-character string. +.SH "RETURN VALUE" +Upon completion, +\fIwcschr\fR() +shall return a pointer to the wide-character code, or a null pointer if +the wide-character code is not found. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcsrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcscmp.3p b/upstream/archlinux/man3p/wcscmp.3p new file mode 100644 index 00000000..8badcf0a --- /dev/null +++ b/upstream/archlinux/man3p/wcscmp.3p @@ -0,0 +1,80 @@ +'\" et +.TH WCSCMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcscmp +\(em compare two wide-character strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcscmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcscmp\fR() +function shall compare the wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of wide-character +codes that differ in the objects being compared. +.SH "RETURN VALUE" +Upon completion, +\fIwcscmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +wide-character string pointed to by +.IR ws1 +is greater than, equal to, or less than the wide-character string +pointed to by +.IR ws2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscasecmp\fR\^(\|)", +.IR "\fIwcsncmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcscoll.3p b/upstream/archlinux/man3p/wcscoll.3p new file mode 100644 index 00000000..544cc31e --- /dev/null +++ b/upstream/archlinux/man3p/wcscoll.3p @@ -0,0 +1,137 @@ +'\" et +.TH WCSCOLL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcscoll, +wcscoll_l +\(em wide-character string comparison using collating information +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcscoll(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +int wcscoll_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwcscoll\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +functions shall compare the wide-character string pointed to by +.IR ws1 +to the wide-character string pointed to by +.IR ws2 , +both interpreted as appropriate to the +.IR LC_COLLATE +category of the current locale, +or the locale represented by +.IR locale , +respectively. +.P +The +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +An application wishing to check for error situations should set +.IR errno +to 0 before calling +\fIwcscoll\fR() +or +\fIwcscoll_l\fR(). +If +.IR errno +is non-zero on return, an error has occurred. +.P +The behavior is undefined if the +.IR locale +argument to +\fIwcscoll_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +Upon successful completion, +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +shall return an integer greater than, equal to, or less than 0, +according to whether the wide-character string pointed to by +.IR ws1 +is greater than, equal to, or less than the wide-character string +pointed to by +.IR ws2 , +when both are interpreted as appropriate to the current locale, +or to the locale represented by +.IR locale , +respectively. On error, +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +shall set +.IR errno , +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The +.IR ws1 +or +.IR ws2 +arguments contain wide-character codes outside the domain of the +collating sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIwcsxfrm\fR() +and +\fIwcscmp\fR() +functions should be used for sorting large lists. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcsxfrm\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcscpy.3p b/upstream/archlinux/man3p/wcscpy.3p new file mode 100644 index 00000000..86d4a54f --- /dev/null +++ b/upstream/archlinux/man3p/wcscpy.3p @@ -0,0 +1,101 @@ +'\" et +.TH WCSCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcpcpy, wcscpy +\(em copy a wide-character string, returning a pointer to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpcpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +wchar_t *wcscpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +For +\fIwcscpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcpcpy\fR() +and +\fIwcscpy\fR() +functions shall copy the wide-character string pointed to by +.IR ws2 +(including the terminating null wide-character code) into the array +pointed to by +.IR ws1 . +.P +The application shall ensure that there is room for at least +.IR wcslen (\c +.IR ws2 )\(pl1 +wide characters in the +.IR ws1 +array, and that the +.IR ws2 +and +.IR ws1 +arrays do not overlap. +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +The +\fIwcpcpy\fR() +function shall return a pointer to the terminating null wide-character +code copied into the +.IR ws1 +buffer. +.P +The +\fIwcscpy\fR() +function shall return +.IR ws1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrcpy\fR\^(\|)", +.IR "\fIwcsdup\fR\^(\|)", +.IR "\fIwcsncpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcscspn.3p b/upstream/archlinux/man3p/wcscspn.3p new file mode 100644 index 00000000..fcc92f71 --- /dev/null +++ b/upstream/archlinux/man3p/wcscspn.3p @@ -0,0 +1,74 @@ +'\" et +.TH WCSCSPN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcscspn +\(em get the length of a complementary wide substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcscspn(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcscspn\fR() +function shall compute the length (in wide characters) of the maximum +initial segment of the wide-character string pointed to by +.IR ws1 +which consists entirely of wide-character codes +.IR not +from the wide-character string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +The +\fIwcscspn\fR() +function shall return the length of the initial substring of +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcsspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsdup.3p b/upstream/archlinux/man3p/wcsdup.3p new file mode 100644 index 00000000..2fb0331f --- /dev/null +++ b/upstream/archlinux/man3p/wcsdup.3p @@ -0,0 +1,93 @@ +'\" et +.TH WCSDUP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsdup +\(em duplicate a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsdup(const wchar_t *\fIstring\fP); +.fi +.SH DESCRIPTION +The +\fIwcsdup\fR() +function is the wide-character equivalent of the +\fIstrdup\fR() +function. +.P +The +\fIwcsdup\fR() +function shall return a pointer to a new wide-character string, +allocated as if by a call to +\fImalloc\fR(), +which is the duplicate of the wide-character string +.IR string . +The returned pointer can be passed to +\fIfree\fR(). +A null pointer is returned if the new wide-character string cannot be +created. +.SH "RETURN VALUE" +Upon successful completion, the +\fIwcsdup\fR() +function shall return a pointer to the newly allocated wide-character +string. Otherwise, it shall return a null pointer and set +.IR errno +to indicate the error. +.SH ERRORS +The +\fIwcsdup\fR() +function shall fail if: +.TP +.BR ENOMEM +Memory large enough for the duplicate string could not be allocated. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +For functions that allocate memory as if by +\fImalloc\fR(), +the application should release such memory when it is no longer +required by a call to +\fIfree\fR(). +For +\fIwcsdup\fR(), +this is the return value. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfree\fR\^(\|)", +.IR "\fIstrdup\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsftime.3p b/upstream/archlinux/man3p/wcsftime.3p new file mode 100644 index 00000000..e409abf9 --- /dev/null +++ b/upstream/archlinux/man3p/wcsftime.3p @@ -0,0 +1,104 @@ +'\" et +.TH WCSFTIME "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsftime +\(em convert date and time to a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsftime(wchar_t *restrict \fIwcs\fP, size_t \fImaxsize\fP, + const wchar_t *restrict \fIformat\fP, const struct tm *restrict \fItimeptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsftime\fR() +function shall be equivalent to the +\fIstrftime\fR() +function, except that: +.IP " *" 4 +The argument +.IR wcs +points to the initial element of an array of wide characters into which +the generated output is to be placed. +.IP " *" 4 +The argument +.IR maxsize +indicates the maximum number of wide characters to be placed in the +output array. +.IP " *" 4 +The argument +.IR format +is a wide-character string and the conversion specifications are +replaced by corresponding sequences of wide characters. +It is unspecified whether an encoding error occurs if the format +string contains +.BR wchar_t +values that do not correspond to members of the character set of the +current locale. +.IP " *" 4 +Field widths specify the number of wide characters instead of the +number of bytes. +.IP " *" 4 +The return value indicates the number of wide characters placed in the +output array. +.P +If copying takes place between objects that overlap, the behavior is +undefined. +.SH "RETURN VALUE" +If the total number of resulting wide-character codes including the +terminating null wide-character code is no more than +.IR maxsize , +\fIwcsftime\fR() +shall return the number of wide-character codes placed into the array +pointed to by +.IR wcs , +not including the terminating null wide-character code. Otherwise, +zero is returned and the contents of the array are unspecified. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrftime\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcslen.3p b/upstream/archlinux/man3p/wcslen.3p new file mode 100644 index 00000000..fed79fa4 --- /dev/null +++ b/upstream/archlinux/man3p/wcslen.3p @@ -0,0 +1,102 @@ +'\" et +.TH WCSLEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcslen, wcsnlen +\(em get length of a fixed-sized wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcslen(const wchar_t *\fIws\fP); +size_t wcsnlen(const wchar_t *\fIws\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +For +\fIwcslen\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcslen\fR() +function shall compute the number of wide-character codes in the +wide-character string to which +.IR ws +points, not including the terminating null wide-character code. +.P +The +\fIwcsnlen\fR() +function shall compute the smaller of the number of wide characters in +the array to which +.IR ws +points, not including any terminating null wide-character code, and the +value of +.IR maxlen . +The +\fIwcsnlen\fR() +function shall never examine more than the first +.IR maxlen +characters of the wide-character array pointed to by +.IR ws . +.SH "RETURN VALUE" +The +\fIwcslen\fR() +function shall return the length of +.IR ws . +.P +The +\fIwcsnlen\fR() +function shall return the number of wide characters preceding the +first null wide-character code in the array to which +.IR ws +points, if +.IR ws +contains a null wide-character code within the first +.IR maxlen +wide characters; otherwise, it shall return +.IR maxlen . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrlen\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsncasecmp.3p b/upstream/archlinux/man3p/wcsncasecmp.3p new file mode 100644 index 00000000..344fdca5 --- /dev/null +++ b/upstream/archlinux/man3p/wcsncasecmp.3p @@ -0,0 +1,43 @@ +'\" et +.TH WCSNCASECMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsncasecmp, +wcsncasecmp_l +\(em case-insensitive wide-character string comparison +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcsncasecmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +int wcsncasecmp_l(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcscasecmp\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsncat.3p b/upstream/archlinux/man3p/wcsncat.3p new file mode 100644 index 00000000..892230ca --- /dev/null +++ b/upstream/archlinux/man3p/wcsncat.3p @@ -0,0 +1,82 @@ +'\" et +.TH WCSNCAT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsncat +\(em concatenate a wide-character string with part of another +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsncat(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsncat\fR() +function shall append not more than +.IR n +wide-character codes (a null wide-character code and wide-character +codes that follow it are not appended) from the array pointed to by +.IR ws2 +to the end of the wide-character string pointed to by +.IR ws1 . +The initial wide-character code of +.IR ws2 +shall overwrite the null wide-character code at the end of +.IR ws1 . +A terminating null wide-character code shall always be appended to the +result. If copying takes place between objects that overlap, the +behavior is undefined. +.SH "RETURN VALUE" +The +\fIwcsncat\fR() +function shall return +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscat\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsncmp.3p b/upstream/archlinux/man3p/wcsncmp.3p new file mode 100644 index 00000000..aab40dc4 --- /dev/null +++ b/upstream/archlinux/man3p/wcsncmp.3p @@ -0,0 +1,83 @@ +'\" et +.TH WCSNCMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsncmp +\(em compare part of two wide-character strings +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcsncmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsncmp\fR() +function shall compare not more than +.IR n +wide-character codes (wide-character codes that follow a null +wide-character code are not compared) from the array pointed to by +.IR ws1 +to the array pointed to by +.IR ws2 . +.P +The sign of a non-zero return value shall be determined by the sign of +the difference between the values of the first pair of wide-character +codes that differ in the objects being compared. +.SH "RETURN VALUE" +Upon successful completion, +\fIwcsncmp\fR() +shall return an integer greater than, equal to, or less than 0, if the +possibly null-terminated array pointed to by +.IR ws1 +is greater than, equal to, or less than the possibly null-terminated +array pointed to by +.IR ws2 , +respectively. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscasecmp\fR\^(\|)", +.IR "\fIwcscmp\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsncpy.3p b/upstream/archlinux/man3p/wcsncpy.3p new file mode 100644 index 00000000..7cd02e15 --- /dev/null +++ b/upstream/archlinux/man3p/wcsncpy.3p @@ -0,0 +1,108 @@ +'\" et +.TH WCSNCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcpncpy, wcsncpy +\(em copy a fixed-size wide-character string, returning a pointer +to its end +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcpncpy(wchar_t restrict *\fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +wchar_t *wcsncpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +For +\fIwcsncpy\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcpncpy\fR() +and +\fIwcsncpy\fR() +functions shall copy not more than +.IR n +wide-character codes (wide-character codes that follow a null +wide-character code are not copied) from the array pointed to by +.IR ws2 +to the array pointed to by +.IR ws1 . +If copying takes place between objects that overlap, the behavior is +undefined. +.P +If the array pointed to by +.IR ws2 +is a wide-character string that is shorter than +.IR n +wide-character codes, null wide-character codes shall be appended to +the copy in the array pointed to by +.IR ws1 , +until +.IR n +wide-character codes in all are written. +.SH "RETURN VALUE" +If any null wide-character codes were written into the +destination, the +\fIwcpncpy\fR() +function shall return the address of the first such null wide-character +code. Otherwise, it shall return +.IR &ws1 [ n ]. +.P +The +\fIwcsncpy\fR() +function shall return +.IR ws1 . +.P +No return values are reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If there is no null wide-character code in the first +.IR n +wide-character codes of the array pointed to by +.IR ws2 , +the result is not null-terminated. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIstrncpy\fR\^(\|)", +.IR "\fIwcscpy\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsnlen.3p b/upstream/archlinux/man3p/wcsnlen.3p new file mode 100644 index 00000000..bed3dff7 --- /dev/null +++ b/upstream/archlinux/man3p/wcsnlen.3p @@ -0,0 +1,40 @@ +'\" et +.TH WCSNLEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsnlen +\(em get length of a fixed-sized wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsnlen(const wchar_t *\fIws\fP, size_t \fImaxlen\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcslen\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsnrtombs.3p b/upstream/archlinux/man3p/wcsnrtombs.3p new file mode 100644 index 00000000..c4c0f54b --- /dev/null +++ b/upstream/archlinux/man3p/wcsnrtombs.3p @@ -0,0 +1,41 @@ +'\" et +.TH WCSNRTOMBS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsnrtombs +\(em convert wide-character string to multi-byte string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsnrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP, + size_t \fInwc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcsrtombs\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcspbrk.3p b/upstream/archlinux/man3p/wcspbrk.3p new file mode 100644 index 00000000..400c3d77 --- /dev/null +++ b/upstream/archlinux/man3p/wcspbrk.3p @@ -0,0 +1,75 @@ +'\" et +.TH WCSPBRK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcspbrk +\(em scan a wide-character string for a wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcspbrk(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcspbrk\fR() +function shall locate the first occurrence in the wide-character string +pointed to by +.IR ws1 +of any wide-character code from the wide-character string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIwcspbrk\fR() +shall return a pointer to the wide-character code or a null pointer if +no wide-character code from +.IR ws2 +occurs in +.IR ws1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcschr\fR\^(\|)", +.IR "\fIwcsrchr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsrchr.3p b/upstream/archlinux/man3p/wcsrchr.3p new file mode 100644 index 00000000..4332fc7c --- /dev/null +++ b/upstream/archlinux/man3p/wcsrchr.3p @@ -0,0 +1,78 @@ +'\" et +.TH WCSRCHR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsrchr +\(em wide-character string scanning operation +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsrchr(const wchar_t *\fIws\fP, wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsrchr\fR() +function shall locate the last occurrence of +.IR wc +in the wide-character string pointed to by +.IR ws . +The application shall ensure that the value of +.IR wc +is a character representable as a type +.BR wchar_t +and a wide-character code corresponding to a valid character in the +current locale. The terminating null wide-character code shall be +considered to be part of the wide-character string. +.SH "RETURN VALUE" +Upon successful completion, +\fIwcsrchr\fR() +shall return a pointer to the wide-character code or a null pointer if +.IR wc +does not occur in the wide-character string. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcschr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsrtombs.3p b/upstream/archlinux/man3p/wcsrtombs.3p new file mode 100644 index 00000000..1ffb8739 --- /dev/null +++ b/upstream/archlinux/man3p/wcsrtombs.3p @@ -0,0 +1,167 @@ +'\" et +.TH WCSRTOMBS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsnrtombs, wcsrtombs +\(em convert a wide-character string to a character string (restartable) +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsnrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP, + size_t \fInwc\fP, size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +size_t wcsrtombs(char *restrict \fIdst\fP, const wchar_t **restrict \fIsrc\fP, + size_t \fIlen\fP, mbstate_t *restrict \fIps\fP); +.fi +.SH DESCRIPTION +For +\fIwcsrtombs\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsrtombs\fR() +function shall convert a sequence of wide characters from the array +indirectly pointed to by +.IR src +into a sequence of corresponding characters, beginning in the +conversion state described by the object pointed to by +.IR ps . +If +.IR dst +is not a null pointer, the converted characters shall then be +stored into the array pointed to by +.IR dst . +Conversion continues up to and including a terminating null wide +character, which shall also be stored. Conversion shall stop +earlier in the following cases: +.IP " *" 4 +When a code is reached that does not correspond to a valid character +.IP " *" 4 +When the next character would exceed the limit of +.IR len +total bytes to be stored in the array pointed to by +.IR dst +(and +.IR dst +is not a null pointer) +.P +Each conversion shall take place as if by a call to the +\fIwcrtomb\fR() +function. +.P +If +.IR dst +is not a null pointer, the pointer object pointed to by +.IR src +shall be assigned either a null pointer (if conversion stopped due to +reaching a terminating null wide character) or the address just past +the last wide character converted (if any). If conversion stopped due +to reaching a terminating null wide character, the resulting state +described shall be the initial conversion state. +.P +If +.IR ps +is a null pointer, the +\fIwcsrtombs\fR() +function shall use its own internal +.BR mbstate_t +object, which is initialized at program start-up to the initial +conversion state. Otherwise, the +.BR mbstate_t +object pointed to by +.IR ps +shall be used to completely describe the current conversion state of +the associated character sequence. +.P +The +\fIwcsnrtombs\fR() +and +\fIwcsrtombs\fR() +functions need not be thread-safe if called with a NULL +.IR ps +argument. +.P +The +\fIwcsnrtombs\fR() +function shall be equivalent to the +\fIwcsrtombs\fR() +function, except that the conversion is limited to the first +.IR nwc +wide characters. +.P +The +\fIwcsrtombs\fR() +function shall not change the setting of +.IR errno +if successful. +.P +The behavior of these functions shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +The implementation shall behave as if no function defined in System Interfaces volume of POSIX.1\(hy2017 +calls these functions. +.SH "RETURN VALUE" +If conversion stops because a code is reached that does not correspond +to a valid character, an encoding error occurs. In this case, these +functions shall store the value of the macro +.BR [EILSEQ] +in +.IR errno +and return (\fBsize_t\fP)\-1; the conversion state is undefined. +Otherwise, these functions shall return the number of bytes in the +resulting character sequence, not including the terminating null (if any). +.SH ERRORS +These functions shall fail if: +.TP +.BR EILSEQ +A wide-character code does not correspond to a valid character. +.P +These functions may fail if: +.TP +.BR EINVAL +.IR ps +points to an object that contains an invalid conversion state. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImbsinit\fR\^(\|)", +.IR "\fIwcrtomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsspn.3p b/upstream/archlinux/man3p/wcsspn.3p new file mode 100644 index 00000000..f8418b33 --- /dev/null +++ b/upstream/archlinux/man3p/wcsspn.3p @@ -0,0 +1,73 @@ +'\" et +.TH WCSSPN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsspn +\(em get the length of a wide substring +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsspn(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsspn\fR() +function shall compute the length (in wide characters) of the +maximum initial segment of the wide-character string pointed to by +.IR ws1 +which consists entirely of wide-character codes from the wide-character +string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +The +\fIwcsspn\fR() +function shall return the length of the initial substring of +.IR ws1 ; +no return value is reserved to indicate an error. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscspn\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsstr.3p b/upstream/archlinux/man3p/wcsstr.3p new file mode 100644 index 00000000..8c3c3d16 --- /dev/null +++ b/upstream/archlinux/man3p/wcsstr.3p @@ -0,0 +1,79 @@ +'\" et +.TH WCSSTR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsstr +\(em find a wide-character substring +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcsstr(const wchar_t *restrict \fIws1\fP, + const wchar_t *restrict \fIws2\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsstr\fR() +function shall locate the first occurrence in the wide-character string +pointed to by +.IR ws1 +of the sequence of wide characters (excluding the terminating null wide +character) in the wide-character string pointed to by +.IR ws2 . +.SH "RETURN VALUE" +Upon successful completion, +\fIwcsstr\fR() +shall return a pointer to the located wide-character string, or a null +pointer if the wide-character string is not found. +.P +If +.IR ws2 +points to a wide-character string with zero length, the function +shall return +.IR ws1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcschr\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstod.3p b/upstream/archlinux/man3p/wcstod.3p new file mode 100644 index 00000000..5a687071 --- /dev/null +++ b/upstream/archlinux/man3p/wcstod.3p @@ -0,0 +1,270 @@ +'\" et +.TH WCSTOD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstod, +wcstof, +wcstold +\(em convert a wide-character string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +double wcstod(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP); +float wcstof(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP); +long double wcstold(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the wide-character +string pointed to by +.IR nptr +to +.BR double , +.BR float , +and +.BR "long double" +representation, respectively. First, they shall decompose the input +wide-character string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by +\fIiswspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as a floating-point constant or +representing infinity or NaN +.IP " 3." 4 +A final wide-character string of one or more unrecognized wide-character +codes, including the terminating null wide-character code of the input +wide-character string +.P +Then they shall attempt to convert the subject sequence to a +floating-point number, and return the result. +.P +The expected form of the subject sequence is an optional +.BR '+' +or +.BR '\-' +sign, then one of the following: +.IP " *" 4 +A non-empty sequence of decimal digits optionally containing a radix +character; then an optional exponent part consisting of the wide +character +.BR 'e' +or the wide character +.BR 'E' , +optionally followed by a +.BR '+' +or +.BR '\-' +wide character, and then followed by one or more decimal digits +.IP " *" 4 +A 0x or 0X, then a non-empty sequence of hexadecimal digits optionally +containing a radix character; then an optional binary exponent part +consisting of the wide character +.BR 'p' +or the wide character +.BR 'P' , +optionally followed by a +.BR '+' +or +.BR '\-' +wide character, and then followed by one or more decimal digits +.IP " *" 4 +One of INF or INFINITY, or any other wide string equivalent except for +case +.IP " *" 4 +One of NAN or NAN(\fIn-wchar-sequence\s-3\dopt\u\s+3\fR), or any other +wide string ignoring case in the NAN part, where: +.RS 4 +.sp +.RS 4 +.nf + +n-wchar-sequence: + digit + nondigit + n-wchar-sequence digit + n-wchar-sequence nondigit +.fi +.P +.RE +.RE +.P +The subject sequence is defined as the longest initial subsequence of +the input wide string, starting with the first non-white-space wide +character, that is of the expected form. The subject sequence contains +no wide characters if the input wide string is not of the expected +form. +.P +If the subject sequence has the expected form for a floating-point +number, the sequence of wide characters starting with the first digit +or the radix character (whichever occurs first) shall be interpreted as +a floating constant according to the rules of the C language, except +that the radix character shall be used in place of a period, and that +if neither an exponent part nor a radix character appears in a decimal +floating-point number, or if a binary exponent part does not appear in +a hexadecimal floating-point number, an exponent part of the +appropriate type with value zero shall be assumed to follow the last +digit in the string. If the subject sequence begins with a +, +the sequence shall be interpreted as negated. A wide-character sequence +INF or INFINITY shall be interpreted as an infinity, if representable +in the return type, else as if it were a floating constant that is too +large for the range of the return type. A wide-character sequence NAN +or NAN(\fIn-wchar-sequence\s-3\dopt\u\s+3\fR) shall be interpreted as a +quiet NaN, if supported in the return type, else as if it were a +subject sequence part that does not have the expected form; the meaning +of the \fIn\fP-wchar sequences is implementation-defined. A pointer to +the final wide string shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +If the subject sequence has the hexadecimal form and FLT_RADIX is a +power of 2, the conversion shall be rounded in an +implementation-defined manner. +.P +The radix character shall be as defined in the current locale +(category +.IR LC_NUMERIC ). +In the POSIX locale, or in a locale where the radix character is not +defined, the radix character shall default to a + +(\c +.BR '.' ). +.P +In other than the C +or POSIX +locale, additional locale-specific subject sequence forms may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0 is returned on error and is also a valid return on success, +an application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcstod\fR(), +\fIwcstof\fR(), +or +\fIwcstold\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to +.BR [EINVAL] . +.P +If the correct value is outside the range of representable values, +\(+-HUGE_VAL, \(+-HUGE_VALF, or \(+-HUGE_VALL shall be returned +(according to the sign of the value), and +.IR errno +shall be set to +.BR [ERANGE] . +.P +If the correct value would cause underflow, a value whose magnitude is +no greater than the smallest normalized positive number in the return +type shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +The +\fIwcstod\fR() +function shall fail if: +.TP +.BR ERANGE +The value to be returned would cause overflow or underflow. +.P +The +\fIwcstod\fR() +function may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +If the subject sequence has the hexadecimal form and FLT_RADIX is not a +power of 2, and the result is not exactly representable, the result +should be one of the two numbers in the appropriate internal format +that are adjacent to the hexadecimal floating source value, with the +extra stipulation that the error should have a correct sign for the +current rounding direction. +.P +If the subject sequence has the decimal form and at most DECIMAL_DIG +(defined in +.IR ) +significant digits, the result should be correctly rounded. If the +subject sequence \fID\fP has the decimal form and more than DECIMAL_DIG +significant digits, consider the two bounding, adjacent decimal strings +\fIL\fP and \fIU\fP, both having DECIMAL_DIG significant digits, such +that the values of \fIL\fP, \fID\fP, and \fIU\fP satisfy +.BR \(dqL <= D <= U\(dq . +The result should be one of the (equal or adjacent) values that would +be obtained by correctly rounding \fIL\fP and \fIU\fP according to the +current rounding direction, with the extra stipulation that the error +with respect to \fID\fP should have a correct sign for the current +rounding direction. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIiswspace\fR\^(\|)", +.IR "\fIlocaleconv\fR\^(\|)", +.IR "\fIsetlocale\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 7" ", " "Locale", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstoimax.3p b/upstream/archlinux/man3p/wcstoimax.3p new file mode 100644 index 00000000..b1bf3b70 --- /dev/null +++ b/upstream/archlinux/man3p/wcstoimax.3p @@ -0,0 +1,105 @@ +'\" et +.TH WCSTOIMAX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstoimax, +wcstoumax +\(em convert a wide-character string to an integer type +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +intmax_t wcstoimax(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +uintmax_t wcstoumax(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall be equivalent to the +\fIwcstol\fR(), +\fIwcstoll\fR(), +\fIwcstoul\fR(), +and +\fIwcstoull\fR() +functions, respectively, except that the initial portion of the wide +string shall be converted to +.BR intmax_t +and +.BR uintmax_t +representation, respectively. +.SH "RETURN VALUE" +These functions shall return the converted value, if any. +.P +If no conversion could be performed, zero shall be returned. If the +correct value is outside the range of representable values, +{INTMAX_MAX}, +{INTMAX_MIN}, +or +{UINTMAX_MAX} +shall be returned (according to the return type and sign of the value, +if any), and +.IR errno +shall be set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcstol\fR\^(\|)", +.IR "\fIwcstoul\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstok.3p b/upstream/archlinux/man3p/wcstok.3p new file mode 100644 index 00000000..a766cbd8 --- /dev/null +++ b/upstream/archlinux/man3p/wcstok.3p @@ -0,0 +1,124 @@ +'\" et +.TH WCSTOK "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstok +\(em split a wide-character string into tokens +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wcstok(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + wchar_t **restrict \fIptr\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +A sequence of calls to +\fIwcstok\fR() +shall break the wide-character string pointed to by +.IR ws1 +into a sequence of tokens, each of which shall be delimited by a +wide-character code from the wide-character string pointed to by +.IR ws2 . +The +.IR ptr +argument points to a caller-provided +.BR wchar_t +pointer into which the +\fIwcstok\fR() +function shall store information necessary for it to continue +scanning the same wide-character string. +.P +The first call in the sequence has +.IR ws1 +as its first argument, and is followed by calls with a null pointer as +their first argument. The separator string pointed to by +.IR ws2 +may be different from call to call. +.P +The first call in the sequence shall search the wide-character string +pointed to by +.IR ws1 +for the first wide-character code that is +.IR not +contained in the current separator string pointed to by +.IR ws2 . +If no such wide-character code is found, then there are no tokens in +the wide-character string pointed to by +.IR ws1 +and +\fIwcstok\fR() +shall return a null pointer. If such a wide-character code is found, +it shall be the start of the first token. +.P +The +\fIwcstok\fR() +function shall then search from there for a wide-character code that +.IR is +contained in the current separator string. If no such wide-character +code is found, the current token extends to the end of the +wide-character string pointed to by +.IR ws1 , +and subsequent searches for a token shall return a null pointer. If +such a wide-character code is found, it shall be overwritten by a null +wide character, which terminates the current token. The +\fIwcstok\fR() +function shall save a pointer to the following wide-character code, +from which the next search for a token shall start. +.P +Each subsequent call, with a null pointer as the value of the first +argument, shall start searching from the saved pointer and behave as +described above. +.P +The implementation shall behave as if no function calls +\fIwcstok\fR(). +.SH "RETURN VALUE" +Upon successful completion, the +\fIwcstok\fR() +function shall return a pointer to the first wide-character code of a +token. Otherwise, if there is no token, +\fIwcstok\fR() +shall return a null pointer. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstol.3p b/upstream/archlinux/man3p/wcstol.3p new file mode 100644 index 00000000..d31ef3a3 --- /dev/null +++ b/upstream/archlinux/man3p/wcstol.3p @@ -0,0 +1,233 @@ +'\" et +.TH WCSTOL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstol, +wcstoll +\(em convert a wide-character string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long wcstol(const wchar_t *restrict \fInptr\fP, wchar_t **restrict \fIendptr\fP, + int \fIbase\fP); +long long wcstoll(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +These functions shall convert the initial portion of the wide-character +string pointed to by +.IR nptr +to +.BR long +and +.BR "long long" , +respectively. First, they shall decompose the input string into three +parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by +\fIiswspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final wide-character string of one or more unrecognized +wide-character codes, including the terminating null wide-character +code of the input wide-character string +.P +Then they shall attempt to convert the subject sequence to an +integer, and return the result. +.P +If +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\-' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\-' +sign, but not including an integer suffix. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +shall be permitted. If the value of +.IR base +is 16, the wide-character code representations of 0x or 0X may +optionally precede the sequence of letters and digits, following the +sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input wide-character string, starting with the first +non-white-space wide-character code that is of the expected form. The +subject sequence contains no wide-character codes if the input +wide-character string is empty or consists entirely of white-space +wide-character code, or if the first non-white-space wide-character +code is other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and +.IR base +is 0, the sequence of wide-character codes starting with the first +digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a +, +the value resulting from the +conversion shall be negated. A pointer to the final wide-character +string shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locale, additional locale-specific subject sequence forms may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{LONG_MIN} +or +{LLONG_MIN} +and +{LONG_MAX} +or +{LLONG_MAX} +are returned on error and are also valid returns on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcstol\fR() +or +\fIwcstoll\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the converted +value, if any. If no conversion could be performed, 0 shall be returned +and +.IR errno +may be set to indicate the error. +If the correct value is outside the range of representable values, +{LONG_MIN}, +{LONG_MAX}, +{LLONG_MIN}, +or +{LLONG_MAX} +shall be returned (according to the sign of the value), and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstold.3p b/upstream/archlinux/man3p/wcstold.3p new file mode 100644 index 00000000..642e94a0 --- /dev/null +++ b/upstream/archlinux/man3p/wcstold.3p @@ -0,0 +1,41 @@ +'\" et +.TH WCSTOLD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstold +\(em convert a wide-character string to a double-precision number +.SH SYNOPSIS +.LP +.nf +#include +.P +long double wcstold(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcstod\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstoll.3p b/upstream/archlinux/man3p/wcstoll.3p new file mode 100644 index 00000000..077b7ba4 --- /dev/null +++ b/upstream/archlinux/man3p/wcstoll.3p @@ -0,0 +1,41 @@ +'\" et +.TH WCSTOLL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstoll +\(em convert a wide-character string to a long integer +.SH SYNOPSIS +.LP +.nf +#include +.P +long long wcstoll(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcstol\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstombs.3p b/upstream/archlinux/man3p/wcstombs.3p new file mode 100644 index 00000000..f9bece0f --- /dev/null +++ b/upstream/archlinux/man3p/wcstombs.3p @@ -0,0 +1,113 @@ +'\" et +.TH WCSTOMBS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstombs +\(em convert a wide-character string to a character string +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcstombs(char *restrict \fIs\fP, const wchar_t *restrict \fIpwcs\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcstombs\fR() +function shall convert the sequence of wide-character codes that are +in the array pointed to by +.IR pwcs +into a sequence of characters that begins in the initial shift state +and store these characters into the array pointed to by +.IR s , +stopping if a character would exceed the limit of +.IR n +total bytes or if a null byte is stored. Each wide-character code +shall be converted as if by a call to +\fIwctomb\fR(), +except that the shift state of +\fIwctomb\fR() +shall not be affected. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.P +No more than +.IR n +bytes shall be modified in the array pointed to by +.IR s . +If copying takes place between objects that overlap, the behavior is +undefined. +If +.IR s +is a null pointer, +\fIwcstombs\fR() +shall return the length required to convert the entire array +regardless of the value of +.IR n , +but no values are stored. +.SH "RETURN VALUE" +If a wide-character code is encountered that does not correspond to a +valid character (of one or more bytes each), +\fIwcstombs\fR() +shall return (\fBsize_t\fP)\-1. Otherwise, +\fIwcstombs\fR() +shall return the number of bytes stored in the character array, not +including any terminating null byte. The array shall not be +null-terminated if the value returned is +.IR n . +.SH ERRORS +The +\fIwcstombs\fR() +function shall fail if: +.TP +.BR EILSEQ +A wide-character code does not correspond to a valid character. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwctomb\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstoul.3p b/upstream/archlinux/man3p/wcstoul.3p new file mode 100644 index 00000000..5375119e --- /dev/null +++ b/upstream/archlinux/man3p/wcstoul.3p @@ -0,0 +1,235 @@ +'\" et +.TH WCSTOUL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstoul, +wcstoull +\(em convert a wide-character string to an unsigned long +.SH SYNOPSIS +.LP +.nf +#include +.P +unsigned long wcstoul(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +unsigned long long wcstoull(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcstoul\fR() +and +\fIwcstoull\fR() +functions shall convert the initial portion of the wide-character +string pointed to by +.IR nptr +to +.BR "unsigned long" +and +.BR "unsigned long long" +representation, respectively. First, they shall decompose the input +wide-character string into three parts: +.IP " 1." 4 +An initial, possibly empty, sequence of white-space wide-character +codes (as specified by +\fIiswspace\fR()) +.IP " 2." 4 +A subject sequence interpreted as an integer represented in some radix +determined by the value of +.IR base +.IP " 3." 4 +A final wide-character string of one or more unrecognized +wide-character codes, including the terminating null wide-character +code of the input wide-character string +.P +Then they shall attempt to convert the subject sequence to an +unsigned integer, and return the result. +.P +If +.IR base +is 0, the expected form of the subject sequence is that of a decimal +constant, octal constant, or hexadecimal constant, any of which may be +preceded by a +.BR '+' +or +.BR '\-' +sign. A decimal constant begins with a non-zero digit, and consists of +a sequence of decimal digits. An octal constant consists of the prefix +.BR '0' +optionally followed by a sequence of the digits +.BR '0' +to +.BR '7' +only. A hexadecimal constant consists of the prefix 0x or 0X followed +by a sequence of the decimal digits and letters +.BR 'a' +(or +.BR 'A' ) +to +.BR 'f' +(or +.BR 'F' ) +with values 10 to 15 respectively. +.P +If the value of +.IR base +is between 2 and 36, the expected form of the subject sequence is a +sequence of letters and digits representing an integer with the radix +specified by +.IR base , +optionally preceded by a +.BR '+' +or +.BR '\-' +sign, but not including an integer suffix. The letters from +.BR 'a' +(or +.BR 'A' ) +to +.BR 'z' +(or +.BR 'Z' ) +inclusive are ascribed the values 10 to 35; only letters whose ascribed +values are less than that of +.IR base +shall be permitted. If the value of +.IR base +is 16, the wide-character codes 0x or 0X may optionally precede the +sequence of letters and digits, following the sign if present. +.P +The subject sequence is defined as the longest initial subsequence of +the input wide-character string, starting with the first wide-character +code that is not white space and is of the expected form. The subject +sequence contains no wide-character codes if the input wide-character +string is empty or consists entirely of white-space wide-character +codes, or if the first wide-character code that is not white space is +other than a sign or a permissible letter or digit. +.P +If the subject sequence has the expected form and +.IR base +is 0, the sequence of wide-character codes starting with the first +digit shall be interpreted as an integer constant. If the subject +sequence has the expected form and the value of +.IR base +is between 2 and 36, it shall be used as the base for conversion, +ascribing to each letter its value as given above. If the subject +sequence begins with a +, +the value resulting from the +conversion shall be negated. A pointer to the final wide-character +string shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +In other than the C +or POSIX +locale, additional locale-specific subject sequence forms may be +accepted. +.P +If the subject sequence is empty or does not have the expected form, no +conversion shall be performed; the value of +.IR nptr +shall be stored in the object pointed to by +.IR endptr , +provided that +.IR endptr +is not a null pointer. +.P +These functions shall not change the setting of +.IR errno +if successful. +.P +Since 0, +{ULONG_MAX}, +and +{ULLONG_MAX} +are returned on error and 0 is also a valid return on success, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcstoul\fR() +or +\fIwcstoull\fR(), +then check +.IR errno . +.SH "RETURN VALUE" +Upon successful completion, the +\fIwcstoul\fR() +and +\fIwcstoull\fR() +functions shall return the converted value, if any. If no conversion +could be performed, 0 shall be returned +and +.IR errno +may be set to indicate the error. +If the correct value is outside the range of representable values, +{ULONG_MAX} +or +{ULLONG_MAX} +respectively shall be returned and +.IR errno +set to +.BR [ERANGE] . +.SH ERRORS +These functions shall fail if: +.TP +.BR EINVAL +The value of +.IR base +is not supported. +.TP +.BR ERANGE +The value to be returned is not representable. +.P +These functions may fail if: +.TP +.BR EINVAL +No conversion could be performed. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfscanf\fR\^(\|)", +.IR "\fIiswalpha\fR\^(\|)", +.IR "\fIwcstod\fR\^(\|)", +.IR "\fIwcstol\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcstoumax.3p b/upstream/archlinux/man3p/wcstoumax.3p new file mode 100644 index 00000000..713aab7d --- /dev/null +++ b/upstream/archlinux/man3p/wcstoumax.3p @@ -0,0 +1,42 @@ +'\" et +.TH WCSTOUMAX "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcstoumax +\(em convert a wide-character string to an integer type +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +uintmax_t wcstoumax(const wchar_t *restrict \fInptr\fP, + wchar_t **restrict \fIendptr\fP, int \fIbase\fP); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIwcstoimax\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcswidth.3p b/upstream/archlinux/man3p/wcswidth.3p new file mode 100644 index 00000000..d1ccdbe1 --- /dev/null +++ b/upstream/archlinux/man3p/wcswidth.3p @@ -0,0 +1,81 @@ +'\" et +.TH WCSWIDTH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcswidth +\(em number of column positions of a wide-character string +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcswidth(const wchar_t *\fIpwcs\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The +\fIwcswidth\fR() +function shall determine the number of column positions required for +.IR n +wide-character codes (or fewer than +.IR n +wide-character codes if a null wide-character code is encountered +before +.IR n +wide-character codes are exhausted) in the string pointed to by +.IR pwcs . +.SH "RETURN VALUE" +The +\fIwcswidth\fR() +function either shall return 0 (if +.IR pwcs +points to a null wide-character code), or return the number of column +positions to be occupied by the wide-character string pointed to by +.IR pwcs , +or return \-1 (if any of the first +.IR n +wide-character codes in the wide-character string pointed to by +.IR pwcs +is not a printable wide-character code). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This function was removed from the final ISO/IEC\ 9899:\|1990/Amendment 1:\|1995 (E), and the return value +for a non-printable wide character is not specified. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcwidth\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 3.103" ", " "Column Position", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcsxfrm.3p b/upstream/archlinux/man3p/wcsxfrm.3p new file mode 100644 index 00000000..d1ec87e1 --- /dev/null +++ b/upstream/archlinux/man3p/wcsxfrm.3p @@ -0,0 +1,163 @@ +'\" et +.TH WCSXFRM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcsxfrm, +wcsxfrm_l +\(em wide-character string transformation +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t wcsxfrm(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +size_t wcsxfrm_l(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwcsxfrm\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions shall transform the wide-character string pointed to by +.IR ws2 +and place the resulting wide-character string into the array pointed to +by +.IR ws1 . +The transformation shall be such that if +\fIwcscmp\fR() +is applied to two transformed wide strings, it shall return a value +greater than, equal to, or less than 0, corresponding to the result of +\fIwcscoll\fR() +and +\fIwcscoll_l\fR() +applied to the same two original wide-character strings, and the same +.IR LC_COLLATE +category of the current locale +or the locale object +.IR locale , +respectively. No more than +.IR n +wide-character codes shall be placed into the resulting array pointed +to by +.IR ws1 , +including the terminating null wide-character code. If +.IR n +is 0, +.IR ws1 +is permitted to be a null pointer. If copying takes place between +objects that overlap, the behavior is undefined. +.P +The +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions shall not change the setting of +.IR errno +if successful. +.P +Since no return value is reserved to indicate an error, an +application wishing to check for error situations should set +.IR errno +to 0, then call +\fIwcsxfrm\fR() +or +\fIwcsxfrm_l\fR(), +then check +.IR errno . +.P +The behavior is undefined if the +.IR locale +argument to +\fIwcsxfrm_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions shall return the length of the transformed wide-character +string (not including the terminating null wide-character code). If the +value returned is +.IR n +or more, the contents of the array pointed to by +.IR ws1 +are unspecified. +.P +On error, the +\fIwcsxfrm\fR() +and +\fIwcsxfrm_l\fR() +functions may set +.IR errno , +but no return value is reserved to indicate an error. +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The wide-character string pointed to by +.IR ws2 +contains wide-character codes outside the domain of the collating +sequence. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The transformation function is such that two transformed wide-character +strings can be ordered by +\fIwcscmp\fR() +as appropriate to collating sequence information in the current locale +(category +.IR LC_COLLATE ). +.P +The fact that when +.IR n +is 0 +.IR ws1 +is permitted to be a null pointer is useful to determine the size of +the +.IR ws1 +array prior to making the transformation. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcscmp\fR\^(\|)", +.IR "\fIwcscoll\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wctob.3p b/upstream/archlinux/man3p/wctob.3p new file mode 100644 index 00000000..27534c7b --- /dev/null +++ b/upstream/archlinux/man3p/wctob.3p @@ -0,0 +1,82 @@ +'\" et +.TH WCTOB "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wctob +\(em wide-character to single-byte conversion +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int wctob(wint_t \fIc\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwctob\fR() +function shall determine whether +.IR c +corresponds to a member of the extended character set whose character +representation is a single byte when in the initial shift state. +.P +The behavior of this function shall be affected by the +.IR LC_CTYPE +category of the current locale. +.SH "RETURN VALUE" +The +\fIwctob\fR() +function shall return EOF if +.IR c +does not correspond to a character with length one in the initial shift +state. Otherwise, it shall return the single-byte representation of +that character as an +.BR "unsigned char" +converted to +.BR int . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIbtowc\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wctomb.3p b/upstream/archlinux/man3p/wctomb.3p new file mode 100644 index 00000000..326e5ec2 --- /dev/null +++ b/upstream/archlinux/man3p/wctomb.3p @@ -0,0 +1,129 @@ +'\" et +.TH WCTOMB "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wctomb +\(em convert a wide-character code to a character +.SH SYNOPSIS +.LP +.nf +#include +.P +int wctomb(char *\fIs\fP, wchar_t \fIwchar\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwctomb\fR() +function shall determine the number of bytes needed to represent the +character corresponding to the wide-character code whose value is +.IR wchar +(including any change in the shift state). It shall store the character +representation (possibly multiple bytes and any special bytes to change +shift state) in the array object pointed to by +.IR s +(if +.IR s +is not a null pointer). At most +{MB_CUR_MAX} +bytes shall be stored. If +.IR wchar +is 0, a null byte shall be stored, preceded by any shift sequence +needed to restore the initial shift state, and +\fIwctomb\fR() +shall be left in the initial shift state. +.P +The behavior of this function is affected by the +.IR LC_CTYPE +category of the current locale. For a state-dependent encoding, this +function shall be placed into its initial state by a call for which its +character pointer argument, +.IR s , +is a null pointer. Subsequent calls with +.IR s +as other than a null pointer shall cause the internal state of the +function to be altered as necessary. A call with +.IR s +as a null pointer shall cause this function to return a non-zero value +if encodings have state dependency, and 0 otherwise. Changing the +.IR LC_CTYPE +category causes the shift state of this function to be unspecified. +.P +The +\fIwctomb\fR() +function need not be thread-safe. +.P +The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2017 +calls +\fIwctomb\fR(). +.SH "RETURN VALUE" +If +.IR s +is a null pointer, +\fIwctomb\fR() +shall return a non-zero or 0 value, if character encodings, +respectively, do or do not have state-dependent encodings. If +.IR s +is not a null pointer, +\fIwctomb\fR() +shall return \-1 if the value of +.IR wchar +does not correspond to a valid character, or return the number of +bytes that constitute the character corresponding to the value of +.IR wchar . +.P +In no case shall the value returned be greater than the value of the +{MB_CUR_MAX} +macro. +.SH ERRORS +The +\fIwctomb\fR() +function shall fail if: +.TP +.BR EILSEQ +An invalid wide-character code is detected. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fImblen\fR\^(\|)", +.IR "\fImbtowc\fR\^(\|)", +.IR "\fImbstowcs\fR\^(\|)", +.IR "\fIwcstombs\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wctrans.3p b/upstream/archlinux/man3p/wctrans.3p new file mode 100644 index 00000000..10d00a94 --- /dev/null +++ b/upstream/archlinux/man3p/wctrans.3p @@ -0,0 +1,141 @@ +'\" et +.TH WCTRANS "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wctrans, +wctrans_l +\(em define character mapping +.SH SYNOPSIS +.LP +.nf +#include +.P +wctrans_t wctrans(const char *\fIcharclass\fP); +wctrans_t wctrans_l(const char *\fIcharclass\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwctrans\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwctrans\fR() +and +\fIwctrans_l\fR() +functions are defined for valid character mapping names identified +in the current locale. The +.IR charclass +is a string identifying a generic character mapping name for which +codeset-specific information is required. The following character +mapping names are defined in all locales: +.BR tolower +and +.BR toupper . +.P +These functions shall return a value of type +.BR wctrans_t , +which can be used as the second argument to subsequent calls of +\fItowctrans\fR() +and +\fItowctrans_l\fR(). +.P +The +\fIwctrans\fR() +and +\fIwctrans_l\fR() +functions shall determine values of +.BR wctrans_t +according to the rules of the coded character set defined by character +mapping information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ). +.P +The values returned by +\fIwctrans\fR() +shall be valid until a call to +\fIsetlocale\fR() +that modifies the category +.IR LC_CTYPE . +.P +The values returned by +\fIwctrans_l\fR() +shall be valid only in calls to +\fItowctrans_l\fR() +with a locale represented by +.IR locale +with the same +.IR LC_CTYPE +category value. +.P +The behavior is undefined if the +.IR locale +argument to +\fIwctrans_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIwctrans\fR() +and +\fIwctrans_l\fR() +functions shall return 0 and may set +.IR errno +to indicate the error if the given character mapping name is not valid +for the current locale (category +.IR LC_CTYPE ); +otherwise, they shall return a non-zero object of type +.BR wctrans_t +that can be used in calls to +\fItowctrans\fR() +and +\fItowctrans_l\fR(). +.SH ERRORS +These functions may fail if: +.TP +.BR EINVAL +The character mapping name pointed to by +.IR charclass +is not valid in the current locale. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fItowctrans\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wctype.3p b/upstream/archlinux/man3p/wctype.3p new file mode 100644 index 00000000..09f8cd45 --- /dev/null +++ b/upstream/archlinux/man3p/wctype.3p @@ -0,0 +1,168 @@ +'\" et +.TH WCTYPE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wctype, +wctype_l +\(em define character class +.SH SYNOPSIS +.LP +.nf +#include +.P +wctype_t wctype(const char *\fIproperty\fP); +wctype_t wctype_l(const char *\fIproperty\fP, locale_t \fIlocale\fP); +.fi +.SH DESCRIPTION +For +\fIwctype\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwctype\fR() +and +\fIwctype_l\fR() +functions are defined for valid character class names as defined +in the current locale +or in the locale represented by +.IR locale , +respectively. +.P +The +.IR property +argument is a string identifying a generic character class for which +codeset-specific type information is required. The following character +class names shall be defined in all locales: +.sp +.RS +.TS +tab(!); +lB lB lB. +T{ +.nf +alnum +alpha +blank +cntrl +T}!T{ +.nf +digit +graph +lower +print +T}!T{ +.nf +punct +space +upper +xdigit +.fi +T} +.TE +.RE +.P +Additional character class names defined in the locale definition file +(category +.IR LC_CTYPE ) +can also be specified. +.P +These functions shall return a value of type +.BR wctype_t , +which can be used as the second argument to subsequent calls of +\fIiswctype\fR() +and +\fIiswctype_l\fR(). +.P +The +\fIwctype\fR() +and +\fIwctype_l\fR() +functions shall determine values of +.BR wctype_t +according to the rules of the coded character set defined by character +type information in the current locale +or in the locale represented by +.IR locale , +respectively (category +.IR LC_CTYPE ). +.P +The values returned by +\fIwctype\fR() +shall be valid until a call to +\fIsetlocale\fR() +that modifies the category +.IR LC_CTYPE . +.P +The values returned by +\fIwctype_l\fR() +shall be valid only in calls to +\fIiswctype_l\fR() +with a locale represented by +.IR locale +with the same +.IR LC_CTYPE +category value. +.P +The behavior is undefined if the +.IR locale +argument to +\fIwctype_l\fR() +is the special locale object LC_GLOBAL_LOCALE or is not a valid locale +object handle. +.SH "RETURN VALUE" +The +\fIwctype\fR() +and +\fIwctype_l\fR() +functions shall return 0 if the given character class name is not +valid for the current locale (category +.IR LC_CTYPE ); +otherwise, they shall return an object of type +.BR wctype_t +that can be used in calls to +\fIiswctype\fR() +and +\fIiswctype_l\fR(). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIiswctype\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wcwidth.3p b/upstream/archlinux/man3p/wcwidth.3p new file mode 100644 index 00000000..4b0c6174 --- /dev/null +++ b/upstream/archlinux/man3p/wcwidth.3p @@ -0,0 +1,78 @@ +'\" et +.TH WCWIDTH "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wcwidth +\(em number of column positions of a wide-character code +.SH SYNOPSIS +.LP +.nf +#include +.P +int wcwidth(wchar_t \fIwc\fP); +.fi +.SH DESCRIPTION +The +\fIwcwidth\fR() +function shall determine the number of column positions required for +the wide character +.IR wc . +The application shall ensure that the value of +.IR wc +is a character representable as a +.BR wchar_t , +and is a wide-character code corresponding to a valid character in +the current locale. +.SH "RETURN VALUE" +The +\fIwcwidth\fR() +function shall either return 0 (if +.IR wc +is a null wide-character code), or return the number of column +positions to be occupied by the wide-character code +.IR wc , +or return \-1 (if +.IR wc +does not correspond to a printable wide-character code). +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +This function was removed from the final ISO/IEC\ 9899:\|1990/Amendment 1:\|1995 (E), and the return value +for a non-printable wide character is not specified. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwcswidth\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wmemchr.3p b/upstream/archlinux/man3p/wmemchr.3p new file mode 100644 index 00000000..b3d0a1ae --- /dev/null +++ b/upstream/archlinux/man3p/wmemchr.3p @@ -0,0 +1,90 @@ +'\" et +.TH WMEMCHR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wmemchr +\(em find a wide character in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemchr(const wchar_t *\fIws\fP, wchar_t \fIwc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwmemchr\fR() +function shall locate the first occurrence of +.IR wc +in the initial +.IR n +wide characters of the object pointed to by +.IR ws . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws +is a valid pointer and the function behaves as if no valid +occurrence of +.IR wc +is found. +.SH "RETURN VALUE" +The +\fIwmemchr\fR() +function shall return a pointer to the located wide character, or a null +pointer if the wide character does not occur in the object. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wmemcmp.3p b/upstream/archlinux/man3p/wmemcmp.3p new file mode 100644 index 00000000..5b72d139 --- /dev/null +++ b/upstream/archlinux/man3p/wmemcmp.3p @@ -0,0 +1,95 @@ +'\" et +.TH WMEMCMP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wmemcmp +\(em compare wide characters in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +int wmemcmp(const wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwmemcmp\fR() +function shall compare the first +.IR n +wide characters of the object pointed to by +.IR ws1 +to the first +.IR n +wide characters of the object pointed to by +.IR ws2 . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws1 +and +.IR ws2 +are valid pointers, and the function shall behave as if the two +objects compare equal. +.SH "RETURN VALUE" +The +\fIwmemcmp\fR() +function shall return an integer greater than, equal to, or less than +zero, respectively, as the object pointed to by +.IR ws1 +is greater than, equal to, or less than the object pointed to by +.IR ws2 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wmemcpy.3p b/upstream/archlinux/man3p/wmemcpy.3p new file mode 100644 index 00000000..49c2df9c --- /dev/null +++ b/upstream/archlinux/man3p/wmemcpy.3p @@ -0,0 +1,90 @@ +'\" et +.TH WMEMCPY "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wmemcpy +\(em copy wide characters in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemcpy(wchar_t *restrict \fIws1\fP, const wchar_t *restrict \fIws2\fP, + size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwmemcpy\fR() +function shall copy +.IR n +wide characters from the object pointed to by +.IR ws2 +to the object pointed to by +.IR ws1 . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws1 +and +.IR ws2 +are valid pointers, and the function shall copy zero wide characters. +.SH "RETURN VALUE" +The +\fIwmemcpy\fR() +function shall return the value of +.IR ws1 . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wmemmove.3p b/upstream/archlinux/man3p/wmemmove.3p new file mode 100644 index 00000000..dcf299a5 --- /dev/null +++ b/upstream/archlinux/man3p/wmemmove.3p @@ -0,0 +1,105 @@ +'\" et +.TH WMEMMOVE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wmemmove +\(em copy wide characters in memory with overlapping areas +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemmove(wchar_t *\fIws1\fP, const wchar_t *\fIws2\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwmemmove\fR() +function shall copy +.IR n +wide characters from the object pointed to by +.IR ws2 +to the object pointed to by +.IR ws1 . +Copying shall take place as if the +.IR n +wide characters from the object pointed to by +.IR ws2 +are first copied into a temporary array of +.IR n +wide characters that does not overlap the objects pointed to by +.IR ws1 +or +.IR ws2 , +and then the +.IR n +wide characters from the temporary array are copied into the object +pointed to by +.IR ws1 . +.P +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws1 +and +.IR ws2 +are valid pointers, and the function shall copy zero wide characters. +.SH "RETURN VALUE" +The +\fIwmemmove\fR() +function shall return the value of +.IR ws1 . +.SH ERRORS +No errors are defined +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemset\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wmemset.3p b/upstream/archlinux/man3p/wmemset.3p new file mode 100644 index 00000000..ecbb76b0 --- /dev/null +++ b/upstream/archlinux/man3p/wmemset.3p @@ -0,0 +1,87 @@ +'\" et +.TH WMEMSET "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wmemset +\(em set wide characters in memory +.SH SYNOPSIS +.LP +.nf +#include +.P +wchar_t *wmemset(wchar_t *\fIws\fP, wchar_t \fIwc\fP, size_t \fIn\fP); +.fi +.SH DESCRIPTION +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIwmemset\fR() +function shall copy the value of +.IR wc +into each of the first +.IR n +wide characters of the object pointed to by +.IR ws . +This function shall not be affected by locale and all +.BR wchar_t +values shall be treated identically. The null wide character and +.BR wchar_t +values not corresponding to valid characters shall not be treated +specially. +.P +If +.IR n +is zero, the application shall ensure that +.IR ws +is a valid pointer, and the function shall copy zero wide characters. +.SH "RETURN VALUE" +The +\fIwmemset\fR() +functions shall return the value of +.IR ws . +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIwmemchr\fR\^(\|)", +.IR "\fIwmemcmp\fR\^(\|)", +.IR "\fIwmemcpy\fR\^(\|)", +.IR "\fIwmemmove\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wordexp.3p b/upstream/archlinux/man3p/wordexp.3p new file mode 100644 index 00000000..ed59f89c --- /dev/null +++ b/upstream/archlinux/man3p/wordexp.3p @@ -0,0 +1,506 @@ +'\" et +.TH WORDEXP "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wordexp, +wordfree +\(em perform word expansions +.SH SYNOPSIS +.LP +.nf +#include +.P +int wordexp(const char *restrict \fIwords\fP, wordexp_t *restrict \fIpwordexp\fP, + int \fIflags\fP); +void wordfree(wordexp_t *\fIpwordexp\fP); +.fi +.SH DESCRIPTION +The +\fIwordexp\fR() +function shall perform word expansions as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6" ", " "Word Expansions", +subject to quoting as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.2" ", " "Quoting", +and place the list of expanded words into the structure pointed to by +.IR pwordexp . +.P +The +.IR words +argument is a pointer to a string containing one or more words to be +expanded. The expansions shall be the same as would be performed by the +command line interpreter if +.IR words +were the part of a command line representing the arguments to a +utility. Therefore, the application shall ensure that +.IR words +does not contain an unquoted + +character or any of the unquoted shell special characters +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' +except in the context of command substitution as specified in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.3" ", " "Command Substitution". +It also shall not contain unquoted parentheses or braces, except +in the context of command or variable substitution. The application +shall ensure that every member of +.IR words +which it expects to have expanded by +\fIwordexp\fR() +does not contain an unquoted initial comment character. The application +shall also ensure that any words which it intends to be ignored +(because they begin or continue a comment) are deleted from +.IR words . +If the argument +.IR words +contains an unquoted comment character (\c +) +that is the beginning of a token, +\fIwordexp\fR() +shall either treat the comment character as a regular character, or +interpret it as a comment indicator and ignore the remainder of +.IR words . +.P +The structure type +.BR wordexp_t +is defined in the +.IR +header and includes at least the following members: +.TS +center box tab(!); +cB | cB | cB +lw(1.25i)B | lw(1.25i)I | lw(2.5i). +Member Type!Member Name!Description +_ +size_t!we_wordc!Count of words matched by \fIwords\fP. +char **!we_wordv!Pointer to list of expanded words. +size_t!we_offs!T{ +Slots to reserve at the beginning of \fIpwordexp\fP\->\fIwe_wordv\fR. +T} +.TE +.P +The +\fIwordexp\fR() +function shall store the number of generated words into +\fIpwordexp\fP\->\fIwe_wordc\fP and a pointer to a list of pointers to +words in \fIpwordexp\fP\->\fIwe_wordv\fP. Each individual field created +during field splitting (see the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.5" ", " "Field Splitting") +or pathname expansion (see the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.6" ", " "Pathname Expansion") +shall be a separate word in the \fIpwordexp\fP\->\fIwe_wordv\fP +list. The words shall be in order as described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6" ", " "Word Expansions". +The first pointer after the last word pointer shall be a null pointer. +The expansion of special parameters described in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.5.2" ", " "Special Parameters" +is unspecified. +.P +It is the caller's responsibility to allocate the storage pointed to by +.IR pwordexp . +The +\fIwordexp\fR() +function shall allocate other space as needed, including memory +pointed to by \fIpwordexp\fP\->\fIwe_wordv\fP. The +\fIwordfree\fR() +function frees any memory associated with +.IR pwordexp +from a previous call to +\fIwordexp\fR(). +.P +The +.IR flags +argument is used to control the behavior of +\fIwordexp\fR(). +The value of +.IR flags +is the bitwise-inclusive OR of zero or more of the following constants, +which are defined in +.IR : +.IP WRDE_APPEND 14 +Append words generated to the ones from a previous call to +\fIwordexp\fR(). +.IP WRDE_DOOFFS 14 +Make use of \fIpwordexp\fP\->\fIwe_offs\fP. If this flag is set, +\fIpwordexp\fP\->\fIwe_offs\fP is used to specify how many null +pointers to add to the beginning of \fIpwordexp\fP\->\fIwe_wordv\fP. +In other words, \fIpwordexp\fP\->\fIwe_wordv\fP shall point to +\fIpwordexp\fP\->\fIwe_offs\fP null pointers, followed by +\fIpwordexp\fP\->\fIwe_wordc\fP word pointers, followed by a null +pointer. +.IP WRDE_NOCMD 14 +If the implementation supports the utilities defined in the Shell and Utilities volume of POSIX.1\(hy2017, +fail if command substitution, as specified in the Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Section 2.6.3" ", " "Command Substitution", +is requested. +.IP WRDE_REUSE 14 +The +.IR pwordexp +argument was passed to a previous successful call to +\fIwordexp\fR(), +and has not been passed to +\fIwordfree\fR(). +The result shall be the same as if the application had called +\fIwordfree\fR() +and then called +\fIwordexp\fR() +without WRDE_REUSE. +.IP WRDE_SHOWERR 14 +Do not redirect +.IR stderr +to +.BR /dev/null . +.IP WRDE_UNDEF 14 +Report error on an attempt to expand an undefined shell variable. +.P +The WRDE_APPEND flag can be used to append a new set of words to those +generated by a previous call to +\fIwordexp\fR(). +The following rules apply to applications when two or more calls to +\fIwordexp\fR() +are made with the same value of +.IR pwordexp +and without intervening calls to +\fIwordfree\fR(): +.IP " 1." 4 +The first such call shall not set WRDE_APPEND. All subsequent calls +shall set it. +.IP " 2." 4 +All of the calls shall set WRDE_DOOFFS, or all shall not set it. +.IP " 3." 4 +After the second and each subsequent call, +\fIpwordexp\fP\->\fIwe_wordv\fP shall point to a list containing the +following: +.RS 4 +.IP " a." 4 +Zero or more null pointers, as specified by WRDE_DOOFFS and +\fIpwordexp\fP\->\fIwe_offs\fP +.IP " b." 4 +Pointers to the words that were in the \fIpwordexp\fP\->\fIwe_wordv\fP +list before the call, in the same order as before +.IP " c." 4 +Pointers to the new words generated by the latest call, in the +specified order +.RE +.IP " 4." 4 +The count returned in \fIpwordexp\fP\->\fIwe_wordc\fP shall be the +total number of words from all of the calls. +.IP " 5." 4 +The application can change any of the fields after a call to +\fIwordexp\fR(), +but if it does it shall reset them to the original value before a +subsequent call, using the same +.IR pwordexp +value, to +\fIwordfree\fR() +or +\fIwordexp\fR() +with the WRDE_APPEND or WRDE_REUSE flag. +.P +If the implementation supports the utilities defined in the Shell and Utilities volume of POSIX.1\(hy2017, +and +.IR words +contains an unquoted character\(em\c +, +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' , +.BR '(' , +.BR ')' , +.BR '{' , +.BR '}' \(em\c +in an inappropriate context, +\fIwordexp\fR() +shall fail, and the number of expanded words shall be 0. +.P +Unless WRDE_SHOWERR is set in +.IR flags , +\fIwordexp\fR() +shall redirect +.IR stderr +to +.BR /dev/null +for any utilities executed as a result of command substitution while +expanding +.IR words . +If WRDE_SHOWERR is set, +\fIwordexp\fR() +may write messages to +.IR stderr +if syntax errors are detected while expanding +.IR words , +unless the +.IR stderr +stream has wide orientation in which case the behavior is undefined. +It is unspecified whether any write errors encountered while +outputting such messages will affect the +.IR stderr +error indicator or the value of +.IR errno . +.P +The application shall ensure that if WRDE_DOOFFS is set, then +\fIpwordexp\fP\->\fIwe_offs\fP has the same value for each +\fIwordexp\fR() +call and +\fIwordfree\fR() +call using a given +.IR pwordexp . +.P +The results are unspecified if WRDE_APPEND and WRDE_REUSE are +both specified. +.br +.P +The following constants are defined as error return values: +.IP WRDE_BADCHAR 14 +One of the unquoted characters\(em\c +, +.BR '|' , +.BR '&' , +.BR ';' , +.BR '<' , +.BR '>' , +.BR '(' , +.BR ')' , +.BR '{' , +.BR '}' \(em\c +appears in +.IR words +in an inappropriate context. +.IP WRDE_BADVAL 14 +Reference to undefined shell variable when WRDE_UNDEF is set in +.IR flags . +.IP WRDE_CMDSUB 14 +Command substitution requested when WRDE_NOCMD was set in +.IR flags . +.IP WRDE_NOSPACE 14 +Attempt to allocate memory failed. +.IP WRDE_SYNTAX 14 +Shell syntax error, such as unbalanced parentheses or unterminated +string. +.SH "RETURN VALUE" +Upon successful completion, +\fIwordexp\fR() +shall return 0. Otherwise, a non-zero value, as described in +.IR , +shall be returned to indicate an error. If +\fIwordexp\fR() +returns the value WRDE_NOSPACE, then \fIpwordexp\fP\->\fIwe_wordc\fP +and \fIpwordexp\fP\->\fIwe_wordv\fP shall be updated to reflect any +words that were successfully expanded. In other error cases, if the +WRDE_APPEND flag was specified, \fIpwordexp\fP->\fIwe_wordc\fP and +\fIpwordexp\fP->\fIwe_wordv\fP shall not be modified. +.P +The +\fIwordfree\fR() +function shall not return a value. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +The +\fIwordexp\fR() +function is intended to be used by an application that wants to do all +of the shell's expansions on a word or words obtained from a user. For +example, if the application prompts for a pathname (or list of +pathnames) and then uses +\fIwordexp\fR() +to process the input, the user could respond with anything that would +be valid as input to the shell. +.P +The WRDE_NOCMD flag is provided for applications that, for security or +other reasons, want to prevent a user from executing shell commands. +Disallowing unquoted shell special characters also prevents unwanted +side-effects, such as executing a command or writing a file. +.P +POSIX.1\(hy2008 does not require the +\fIwordexp\fR() +function to be thread-safe if passed an expression referencing an +environment variable while any other thread is concurrently modifying +any environment variable; see +.IR "\fIexec\fR\^". +.P +Even though the WRDE_SHOWERR flag allows the implementation to write +messages to +.IR stderr +during command substitution or syntax errors, this standard does not +provide any way to detect write failures during the output of such +messages. +.P +Applications which use wide-character output functions with +.IR stderr +should ensure that any calls to +\fIwordexp\fR() +do not write to +.IR stderr , +by avoiding use of the WRDE_SHOWERR flag. +.SH RATIONALE +This function was included as an alternative to +\fIglob\fR(). +There had been continuing controversy over exactly what features should +be included in +\fIglob\fR(). +It is hoped that by providing +\fIwordexp\fR() +(which provides all of the shell word expansions, but which may be slow +to execute) and +\fIglob\fR() +(which is faster, but which only performs pathname expansion, without +tilde or parameter expansion) this will satisfy the majority of +applications. +.P +While +\fIwordexp\fR() +could be implemented entirely as a library routine, it is expected that +most implementations run a shell in a subprocess to do the expansion. +.P +Two different approaches have been proposed for how the required +information might be presented to the shell and the results returned. +They are presented here as examples. +.P +One proposal is to extend the +.IR echo +utility by adding a +.BR \-q +option. This option would cause +.IR echo +to add a + +before each + +and + +that occurs within an argument. The +\fIwordexp\fR() +function could then invoke the shell as follows: +.sp +.RS 4 +.nf + +(void) strcpy(buffer, "echo -q"); +(void) strcat(buffer, \fIwords\fP); +if ((flags & WRDE_SHOWERR) == 0) + (void) strcat(buffer, "2>/dev/null"); +f = popen(buffer, "r"); +.fi +.P +.RE +.P +The +\fIwordexp\fR() +function would read the resulting output, remove unquoted + +characters, and break into words at unquoted + +characters. If the WRDE_NOCMD flag was set, +\fIwordexp\fR() +would have to scan +.IR words +before starting the subshell to make sure that there would be no +command substitution. In any case, it would have to scan +.IR words +for unquoted special characters. +.P +Another proposal is to add the following options to +.IR sh : +.IP "\fB\-w\fP\ \fIwordlist\fR" 6 +.br +This option provides a wordlist expansion service to applications. The +words in +.IR wordlist +shall be expanded and the following written to standard output: +.RS 6 +.IP " 1." 4 +The count of the number of words after expansion, in decimal, followed +by a null byte +.IP " 2." 4 +The number of bytes needed to represent the expanded words (not +including null separators), in decimal, followed by a null byte +.IP " 3." 4 +The expanded words, each terminated by a null byte +.P +If an error is encountered during word expansion, +.IR sh +exits with a non-zero status after writing the former to report any +words successfully expanded +.RE +.IP "\fB\-P\fP" 6 +Run in ``protected'' mode. If specified with the +.BR \-w +option, no command substitution shall be performed. +.P +With these options, +\fIwordexp\fR() +could be implemented fairly simply by creating a subprocess using +\fIfork\fR() +and executing +.IR sh +using the line: +.sp +.RS 4 +.nf + +execl(<\fIshell path\fP>, "sh", "-P", "-w", \fIwords\fP, (char *)0); +.fi +.P +.RE +.P +after directing standard error to +.BR /dev/null . +.P +It seemed objectionable for a library routine to write messages to +standard error, unless explicitly requested, so +\fIwordexp\fR() +is required to redirect standard error to +.BR /dev/null +to ensure that no messages are generated, even for commands executed +for command substitution. The WRDE_SHOWERR flag can be specified to +request that error messages be written. +.P +The WRDE_REUSE flag allows the implementation to avoid the expense of +freeing and reallocating memory, if that is possible. A minimal +implementation can call +\fIwordfree\fR() +when WRDE_REUSE is set. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIexec\fR\^", +.IR "\fIfnmatch\fR\^(\|)", +.IR "\fIglob\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP" +.P +The Shell and Utilities volume of POSIX.1\(hy2017, +.IR "Chapter 2" ", " "Shell Command Language" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wprintf.3p b/upstream/archlinux/man3p/wprintf.3p new file mode 100644 index 00000000..2ce2577a --- /dev/null +++ b/upstream/archlinux/man3p/wprintf.3p @@ -0,0 +1,41 @@ +'\" et +.TH WPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wprintf +\(em print formatted wide-character output +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int wprintf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwprintf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/write.3p b/upstream/archlinux/man3p/write.3p new file mode 100644 index 00000000..5a7e03cc --- /dev/null +++ b/upstream/archlinux/man3p/write.3p @@ -0,0 +1,739 @@ +'\" et +.TH WRITE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +pwrite, +write +\(em write on a file +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t pwrite(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP, + off_t \fIoffset\fP); +ssize_t write(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP); +.fi +.SH DESCRIPTION +The +\fIwrite\fR() +function shall attempt to write +.IR nbyte +bytes from the buffer pointed to by +.IR buf +to the file associated with the open file descriptor, +.IR fildes . +.P +Before any action described below is taken, and if +.IR nbyte +is zero and the file is a regular file, the +\fIwrite\fR() +function may detect and return errors as described below. In the +absence of errors, or if error detection is not performed, the +\fIwrite\fR() +function shall return zero and have no other results. If +.IR nbyte +is zero and the file is not a regular file, the results are +unspecified. +.P +On a regular file or other file capable of seeking, the actual writing +of data shall proceed from the position in the file indicated by the +file offset associated with +.IR fildes . +Before successful return from +\fIwrite\fR(), +the file offset shall be incremented by the number of bytes actually +written. On a regular file, if the position of the last byte written +is greater than or equal to the length of the file, +the length of the file shall be set to this position plus one. +.P +On a file not capable of seeking, writing shall always take place +starting at the current position. The value of a file offset associated +with such a device is undefined. +.P +If the O_APPEND flag of the file status flags is set, +the file offset shall be set to the end of the file prior to each write +and no intervening file modification operation shall occur between +changing the file offset and the write operation. +.P +If a +\fIwrite\fR() +requests that more bytes be written than there is room for (for +example, +the file size limit of the process or +the physical end of a medium), only as many bytes as there is room for +shall be written. For example, suppose there is space for 20 bytes more +in a file before reaching a limit. A write of 512 bytes will return +20. The next write of a non-zero number of bytes would give a failure +return (except as noted below). +.P +If the request would cause the file size to exceed the soft file size +limit for the process and there is no room for any bytes to be written, +the request shall fail and the implementation shall generate the +SIGXFSZ signal for the thread. +.P +If +\fIwrite\fR() +is interrupted by a signal before it writes any data, it shall +return \-1 with +.IR errno +set to +.BR [EINTR] . +.P +If +\fIwrite\fR() +is interrupted by a signal after it successfully writes some data, it +shall return the number of bytes written. +.P +If the value of +.IR nbyte +is greater than +{SSIZE_MAX}, +the result is implementation-defined. +.P +After a +\fIwrite\fR() +to a regular file has successfully returned: +.IP " *" 4 +Any successful +\fIread\fR() +from each byte position in the file that was modified by that write +shall return the data specified by the +\fIwrite\fR() +for that position until such byte positions are again modified. +.IP " *" 4 +Any subsequent successful +\fIwrite\fR() +to the same byte position in the file shall overwrite that file data. +.br +.P +Write requests to a pipe or FIFO shall be handled in the same way +as a regular file with the following exceptions: +.IP " *" 4 +There is no file offset associated with a pipe, hence each write +request shall append to the end of the pipe. +.IP " *" 4 +Write requests of +{PIPE_BUF} +bytes or less shall not be interleaved with data from other processes +doing writes on the same pipe. Writes of greater than +{PIPE_BUF} +bytes may have data interleaved, on arbitrary boundaries, with writes +by other processes, whether or not the O_NONBLOCK flag of the file +status flags is set. +.IP " *" 4 +If the O_NONBLOCK flag is clear, a write request may cause the thread +to block, but on normal completion it shall return +.IR nbyte . +.IP " *" 4 +If the O_NONBLOCK flag is set, +\fIwrite\fR() +requests shall be handled differently, in the following ways: +.RS 4 +.IP -- 4 +The +\fIwrite\fR() +function shall not block the thread. +.IP -- 4 +A write request for +{PIPE_BUF} +or fewer bytes shall have the following effect: if there is sufficient +space available in the pipe, +\fIwrite\fR() +shall transfer all the data and return the number of bytes requested. +Otherwise, +\fIwrite\fR() +shall transfer no data and return \-1 with +.IR errno +set to +.BR [EAGAIN] . +.IP -- 4 +A write request for more than +{PIPE_BUF} +bytes shall cause one of the following: +.RS 4 +.IP -- 4 +When at least one byte can be written, transfer what it can and return +the number of bytes written. When all data previously written to the +pipe is read, it shall transfer at least +{PIPE_BUF} +bytes. +.IP -- 4 +When no data can be written, transfer no data, and return \-1 with +.IR errno +set to +.BR [EAGAIN] . +.RE +.RE +.P +When attempting to write to a file descriptor (other than a pipe or +FIFO) that supports non-blocking writes and cannot accept the data +immediately: +.IP " *" 4 +If the O_NONBLOCK flag is clear, +\fIwrite\fR() +shall block the calling thread until the data can be accepted. +.IP " *" 4 +If the O_NONBLOCK flag is set, +\fIwrite\fR() +shall not block the thread. If some data can be written without +blocking the thread, +\fIwrite\fR() +shall write what it can and return the number of bytes written. +Otherwise, it shall return \-1 and set +.IR errno +to +.BR [EAGAIN] . +.P +Upon successful completion, where +.IR nbyte +is greater than 0, +\fIwrite\fR() +shall mark for update the last data modification and last file +status change timestamps of the file, and if the file is a regular file, +the S_ISUID and S_ISGID bits of the file mode may be cleared. +.P +For regular files, no data transfer shall occur past the offset maximum +established in the open file description associated with +.IR fildes . +.P +If +.IR fildes +refers to a socket, +\fIwrite\fR() +shall be equivalent to +\fIsend\fR() +with no flags set. +.P +If the O_DSYNC bit has been set, +write I/O operations on the file descriptor shall complete as defined +by synchronized I/O data integrity completion. +.P +If the O_SYNC bit has been set, write I/O operations on the file +descriptor shall complete as defined by synchronized I/O file +integrity completion. +.P +If +.IR fildes +refers to a shared memory object, the result of the +\fIwrite\fR() +function is unspecified. +.P +If +.IR fildes +refers to a typed memory object, the result of the +\fIwrite\fR() +function is unspecified. +.P +If +.IR fildes +refers to a STREAM, the operation of +\fIwrite\fR() +shall be determined by the values of the minimum and maximum +.IR nbyte +range (packet size) accepted by the STREAM. These values are determined +by the topmost STREAM module. If +.IR nbyte +falls within the packet size range, +.IR nbyte +bytes shall be written. If +.IR nbyte +does not fall within the range and the minimum packet size value is 0, +\fIwrite\fR() +shall break the buffer into maximum packet size segments prior to +sending the data downstream (the last segment may contain less than the +maximum packet size). If +.IR nbyte +does not fall within the range and the minimum value is non-zero, +\fIwrite\fR() +shall fail with +.IR errno +set to +.BR [ERANGE] . +Writing a zero-length buffer (\c +.IR nbyte +is 0) to a STREAMS device sends 0 bytes with 0 returned. However, +writing a zero-length buffer to a STREAMS-based pipe or FIFO sends no +message and 0 is returned. The process may issue I_SWROPT +\fIioctl\fR() +to enable zero-length messages to be sent across the pipe or FIFO. +.P +When writing to a STREAM, data messages are created with a priority +band of 0. When writing to a STREAM that is not a pipe or FIFO: +.IP " *" 4 +If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM +write queue is full due to internal flow control conditions), +\fIwrite\fR() +shall block until data can be accepted. +.IP " *" 4 +If O_NONBLOCK is set and the STREAM cannot accept data, +\fIwrite\fR() +shall return \-1 and set +.IR errno +to +.BR [EAGAIN] . +.IP " *" 4 +If O_NONBLOCK is set and part of the buffer has been written while a +condition in which the STREAM cannot accept additional data occurs, +\fIwrite\fR() +shall terminate and return the number of bytes written. +.P +In addition, +\fIwrite\fR() +shall fail if the STREAM head has processed an asynchronous error +before the call. In this case, the value of +.IR errno +does not reflect the result of +\fIwrite\fR(), +but reflects the prior error. +.P +The +\fIpwrite\fR() +function shall be equivalent to +\fIwrite\fR(), +except that it writes into a given position and does not change the +file offset (regardless of whether O_APPEND is set). The first three +arguments to +\fIpwrite\fR() +are the same as +\fIwrite\fR() +with the addition of a fourth argument +.IR offset +for the desired position inside the file. An attempt to perform a +\fIpwrite\fR() +on a file that is incapable of seeking shall result in an error. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the number of +bytes actually written to the file associated with +.IR fildes . +This number shall never be greater than +.IR nbyte . +Otherwise, \-1 shall be returned and +.IR errno +set to indicate the error. +.SH ERRORS +These functions shall fail if: +.TP +.BR EAGAIN +The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK flag +is set for the file descriptor, and the thread would be delayed in the +\fIwrite\fR() +operation. +.TP +.BR EBADF +The +.IR fildes +argument is not a valid file descriptor open for writing. +.TP +.BR EFBIG +An attempt was made to write a file that exceeds the +implementation-defined maximum file size +or the file size limit of the process, +and there was no room for any bytes to be written. +.TP +.BR EFBIG +The file is a regular file, +.IR nbyte +is greater than 0, and the starting position is greater than or equal +to the offset maximum established in the open file description +associated with +.IR fildes . +.TP +.BR EINTR +The write operation was terminated due to the receipt of a signal, and +no data was transferred. +.TP +.BR EIO +The process is a member of a background process group attempting to +write to its controlling terminal, TOSTOP is set, the calling thread +is not blocking SIGTTOU, the process is not ignoring SIGTTOU, +and the process group of the process is orphaned. This error may also +be returned under implementation-defined conditions. +.TP +.BR ENOSPC +There was no free space remaining on the device containing the file. +.TP +.BR ERANGE +The transfer request size was outside the range supported by the +STREAMS file associated with +.IR fildes . +.P +The +\fIpwrite\fR() +function shall fail if: +.TP +.BR EINVAL +The file is a regular file or block special file, and the +.IR offset +argument is negative. The file offset shall remain unchanged. +.TP +.BR ESPIPE +The file is incapable of seeking. +.P +The +\fIwrite\fR() +function shall fail if: +.TP +.BR EAGAIN +The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the write operation. +.TP +.BR EAGAIN " or " EWOULDBLOCK +.br +The file is a socket, the O_NONBLOCK flag is set for the file +descriptor, and the thread would be delayed in the write operation. +.TP +.BR ECONNRESET +A write was attempted on a socket that is not connected. +.TP +.BR EPIPE +An attempt is made to write to a pipe or FIFO that is not open for +reading by any process, or that only has one end open. A SIGPIPE signal +shall also be sent to the thread. +.TP +.BR EPIPE +A write was attempted on a socket that is shut down for writing, or is +no longer connected. In the latter case, if the socket is of type +SOCK_STREAM, a SIGPIPE signal shall also be sent to the thread. +.P +These functions may fail if: +.TP +.BR EINVAL +The STREAM or multiplexer referenced by +.IR fildes +is linked (directly or indirectly) downstream from a multiplexer. +.TP +.BR EIO +A physical I/O error has occurred. +.TP +.BR ENOBUFS +Insufficient resources were available in the system to perform the +operation. +.TP +.BR ENXIO +A request was made of a nonexistent device, or the request was outside +the capabilities of the device. +.TP +.BR ENXIO +A hangup occurred on the STREAM being written to. +.P +A write to a STREAMS file may fail if an error message has been +received at the STREAM head. In this case, +.IR errno +is set to the value included in the error message. +.br +.P +The +\fIwrite\fR() +function may fail if: +.TP +.BR EACCES +A write was attempted on a socket and the calling +process does not have appropriate privileges. +.TP +.BR ENETDOWN +A write was attempted on a socket and the local network interface used +to reach the destination is down. +.TP +.BR ENETUNREACH +.br +A write was attempted on a socket and no route to the network is +present. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Writing from a Buffer" +.P +The following example writes data from the buffer pointed to by +.IR buf +to the file associated with the file descriptor +.IR fd . +.sp +.RS 4 +.nf + +#include +#include +\&... +char buf[20]; +size_t nbytes; +ssize_t bytes_written; +int fd; +\&... +strcpy(buf, "This is a test\en"); +nbytes = strlen(buf); +.P +bytes_written = write(fd, buf, nbytes); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +See also the RATIONALE section in +\fIread\fR(). +.P +An attempt to write to a pipe or FIFO has several major +characteristics: +.IP " *" 4 +\fIAtomic/non-atomic\fP: A write is atomic if the whole amount written +in one operation is not interleaved with data from any other process. +This is useful when there are multiple writers sending data to a single +reader. Applications need to know how large a write request can be +expected to be performed atomically. This maximum is called +{PIPE_BUF}. +This volume of POSIX.1\(hy2017 does not say whether write requests for more than +{PIPE_BUF} +bytes are atomic, but requires that writes of +{PIPE_BUF} +or fewer bytes shall be atomic. +.IP " *" 4 +\fIBlocking/immediate\fP: Blocking is only possible with O_NONBLOCK +clear. If there is enough space for all the data requested to be +written immediately, the implementation should do so. Otherwise, the +calling thread may block; that is, pause until enough space is +available for writing. The effective size of a pipe or FIFO (the +maximum amount that can be written in one operation without blocking) +may vary dynamically, depending on the implementation, so it is not +possible to specify a fixed value for it. +.IP " *" 4 +\fIComplete/partial/deferred\fP: A write request: +.RS 4 +.sp +.RS 4 +.nf + +int fildes; +size_t nbyte; +ssize_t ret; +char *buf; +.P +ret = write(fildes, buf, nbyte); +.fi +.P +.RE +.P +may return: +.IP Complete 10 +\fIret\fP=\fInbyte\fP +.IP Partial 10 +\fIret\fP<\fInbyte\fP +.RS 10 +.P +This shall never happen if +.IR nbyte \(<=\c +{PIPE_BUF}. +If it does happen (with +.IR nbyte >\c +{PIPE_BUF}), +\&this volume of POSIX.1\(hy2017 does not guarantee atomicity, even if +.IR ret \(<=\c +{PIPE_BUF}, +because atomicity is guaranteed according to the amount +.IR requested , +not the amount +.IR written . +.RE +.IP Deferred: 10 +\fIret\fP=\-1, \fIerrno\fP=[EAGAIN] +.RS 10 +.P +This error indicates that a later request may succeed. It does not +indicate that it +.IR shall +succeed, even if +.IR nbyte \(<=\c +{PIPE_BUF}, +because if no process reads from the pipe or FIFO, the write never +succeeds. An application could usefully count the number of times +.BR [EAGAIN] +is caused by a particular value of +.IR nbyte >\c +{PIPE_BUF} +and perhaps do later writes with a smaller value, on the assumption +that the effective size of the pipe may have decreased. +.RE +.P +Partial and deferred writes are only possible with O_NONBLOCK set. +.RE +.P +The relations of these properties are shown in the following tables: +.TS +center box tab(!); +cB s s s +cB | cB cB c +l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i). +Write to a Pipe or FIFO with O_NONBLOCK \fIclear\fP +_ +Immediately Writable:!None!Some!\fInbyte\fP +_ +\fInbyte\fP\(<={PIPE_BUF}!Atomic blocking!Atomic blocking!Atomic immediate +!\fInbyte\fP!\fInbyte\fP!\fInbyte\fP +_ +\fInbyte\fP>{PIPE_BUF}!Blocking \fInbyte\fP!Blocking \fInbyte\fP!Blocking \fInbyte\fP +.TE +.P +If the O_NONBLOCK flag is clear, a write request shall block if the +amount writable immediately is less than that requested. If the flag is +set (by +\fIfcntl\fR()), +a write request shall never block. +.TS +center box tab(!); +cB s s s +cB | cB cB c +l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i). +Write to a Pipe or FIFO with O_NONBLOCK \fIset\fP +_ +Immediately Writable:!None!Some!\fInbyte\fP +_ +\fInbyte\fP\(<={PIPE_BUF}!\-1, [EAGAIN]!\-1, [EAGAIN]!Atomic \fInbyte\fP +_ +\fInbyte\fP>{PIPE_BUF}!\-1, [EAGAIN]!<\fInbyte\fP or \-1,!\(<=\fInbyte\fP or \-1, +!![EAGAIN]![EAGAIN] +.TE +.P +There is no exception regarding partial writes when O_NONBLOCK is set. +With the exception of writing to an empty pipe, this volume of POSIX.1\(hy2017 does not specify +exactly when a partial write is performed since that would require +specifying internal details of the implementation. Every application +should be prepared to handle partial writes when O_NONBLOCK is set and +the requested amount is greater than +{PIPE_BUF}, +just as every application should be prepared to handle partial writes +on other kinds of file descriptors. +.P +The intent of forcing writing at least one byte if any can be written +is to assure that each write makes progress if there is any room in the +pipe. If the pipe is empty, +{PIPE_BUF} +bytes must be written; if not, at least some progress must have been +made. +.P +Where this volume of POSIX.1\(hy2017 requires \-1 to be returned and +.IR errno +set to +.BR [EAGAIN] , +most historical implementations return zero (with the O_NDELAY +flag set, which is the historical predecessor of O_NONBLOCK, but is not +itself in this volume of POSIX.1\(hy2017). The error indications in this volume of POSIX.1\(hy2017 were chosen so that an +application can distinguish these cases from end-of-file. While +\fIwrite\fR() +cannot receive an indication of end-of-file, +\fIread\fR() +can, and the two functions have similar return values. Also, some +existing systems (for example, Eighth Edition) permit a write of zero +bytes to +mean that the reader should get an end-of-file indication; for those +systems, a return value of zero from +\fIwrite\fR() +indicates a successful write of an end-of-file indication. +.P +Implementations are allowed, but not required, to perform error +checking for +\fIwrite\fR() +requests of zero bytes. +.P +The concept of a +{PIPE_MAX} +limit (indicating the maximum number of bytes that can be written to a +pipe in a single operation) was considered, but rejected, because this +concept would unnecessarily limit application writing. +.P +See also the discussion of O_NONBLOCK in +\fIread\fR(). +.P +Writes can be serialized with respect to other reads and writes. If a +\fIread\fR() +of file data can be proven (by any means) to occur after a +\fIwrite\fR() +of the data, it must reflect that +\fIwrite\fR(), +even if the calls are made by different processes. A similar +requirement applies to multiple write operations to the same file +position. This is needed to guarantee the propagation of data from +\fIwrite\fR() +calls to subsequent +\fIread\fR() +calls. This requirement is particularly significant for networked file +systems, where some caching schemes violate these semantics. +.P +Note that this is specified in terms of +\fIread\fR() +and +\fIwrite\fR(). +The XSI extensions +\fIreadv\fR() +and +\fIwritev\fR() +also obey these semantics. A new ``high-performance'' write +analog that did not follow these serialization requirements would also +be permitted by this wording. This volume of POSIX.1\(hy2017 is also silent about any effects of +application-level caching (such as that done by +.IR stdio ). +.P +This volume of POSIX.1\(hy2017 does not specify the value of the file offset after an error is +returned; there are too many cases. For programming errors, such as +.BR [EBADF] , +the concept is meaningless since no file is involved. For errors that +are detected immediately, such as +.BR [EAGAIN] , +clearly the pointer should not change. After an interrupt or hardware +error, however, an updated value would be very useful and is the +behavior of many implementations. +.P +This volume of POSIX.1\(hy2017 does not specify the behavior of concurrent writes to a +regular file from multiple threads, except that each write +is atomic (see +.IR "Section 2.9.7" ", " "Thread Interactions with Regular File Operations"). +Applications should use some form of concurrency control. +.P +This volume of POSIX.1\(hy2017 intentionally does not specify any +\fIpwrite\fR() +errors related to pipes, FIFOs, and sockets other than +.BR [ESPIPE] . +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIchmod\fR\^(\|)", +.IR "\fIcreat\fR\^(\|)", +.IR "\fIdup\fR\^(\|)", +.IR "\fIfcntl\fR\^(\|)", +.IR "\fIgetrlimit\fR\^(\|)", +.IR "\fIlseek\fR\^(\|)", +.IR "\fIopen\fR\^(\|)", +.IR "\fIpipe\fR\^(\|)", +.IR "\fIread\fR\^(\|)", +.IR "\fIulimit\fR\^(\|)", +.IR "\fIwritev\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/writev.3p b/upstream/archlinux/man3p/writev.3p new file mode 100644 index 00000000..45fc3e57 --- /dev/null +++ b/upstream/archlinux/man3p/writev.3p @@ -0,0 +1,171 @@ +'\" et +.TH WRITEV "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +writev +\(em write a vector +.SH SYNOPSIS +.LP +.nf +#include +.P +ssize_t writev(int \fIfildes\fP, const struct iovec *\fIiov\fP, int \fIiovcnt\fP); +.fi +.SH DESCRIPTION +The +\fIwritev\fR() +function shall be equivalent to +\fIwrite\fR(), +except as described below. The +\fIwritev\fR() +function shall gather output data from the +.IR iovcnt +buffers specified by the members of the +.IR iov +array: +.IR iov [0], +.IR iov [1], +\&.\|.\|., \fIiov\fR[\fIiovcnt\fR\-1]. +The +.IR iovcnt +argument is valid if greater than 0 and less than or equal to +{IOV_MAX}, +as defined in +.IR . +.P +Each +.IR iovec +entry specifies the base address and length of an area in memory from +which data should be written. The +\fIwritev\fR() +function shall always write a complete area before proceeding to the +next. +.P +If +.IR fildes +refers to a regular file and all of the +.IR iov_len +members in the array pointed to by +.IR iov +are 0, +\fIwritev\fR() +shall return 0 and have no other effect. For other file types, the +behavior is unspecified. +.P +If the sum of the +.IR iov_len +values is greater than +{SSIZE_MAX}, +the operation shall fail and no data shall be transferred. +.SH "RETURN VALUE" +Upon successful completion, +\fIwritev\fR() +shall return the number of bytes actually written. Otherwise, it shall +return a value of \-1, the file-pointer shall remain unchanged, and +.IR errno +shall be set to indicate an error. +.SH ERRORS +Refer to +.IR "\fIwrite\fR\^(\|)". +.P +In addition, the +\fIwritev\fR() +function shall fail if: +.TP +.BR EINVAL +The sum of the +.IR iov_len +values in the +.IR iov +array would overflow an +.BR ssize_t . +.P +The +\fIwritev\fR() +function may fail and set +.IR errno +to: +.TP +.BR EINVAL +The +.IR iovcnt +argument was less than or equal to 0, or greater than +{IOV_MAX}. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +.SS "Writing Data from an Array" +.P +The following example writes data from the buffers specified by members +of the +.IR iov +array to the file associated with the file descriptor +.IR fd . +.sp +.RS 4 +.nf + +#include +#include +#include +\&... +ssize_t bytes_written; +int fd; +char *buf0 = "short string\en"; +char *buf1 = "This is a longer string\en"; +char *buf2 = "This is the longest string in this example\en"; +int iovcnt; +struct iovec iov[3]; +.P +iov[0].iov_base = buf0; +iov[0].iov_len = strlen(buf0); +iov[1].iov_base = buf1; +iov[1].iov_len = strlen(buf1); +iov[2].iov_base = buf2; +iov[2].iov_len = strlen(buf2); +\&... +iovcnt = sizeof(iov) / sizeof(struct iovec); +.P +bytes_written = writev(fd, iov, iovcnt); +\&... +.fi +.P +.RE +.SH "APPLICATION USAGE" +None. +.SH RATIONALE +Refer to +.IR "\fIwrite\fR\^(\|)". +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIreadv\fR\^(\|)", +.IR "\fIwrite\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB\fP", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/wscanf.3p b/upstream/archlinux/man3p/wscanf.3p new file mode 100644 index 00000000..1f09310c --- /dev/null +++ b/upstream/archlinux/man3p/wscanf.3p @@ -0,0 +1,41 @@ +'\" et +.TH WSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +wscanf +\(em convert formatted wide-character input +.SH SYNOPSIS +.LP +.nf +#include +#include +.P +int wscanf(const wchar_t *restrict \fIformat\fP, ...); +.fi +.SH DESCRIPTION +Refer to +.IR "\fIfwscanf\fR\^(\|)". +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . diff --git a/upstream/archlinux/man3p/y0.3p b/upstream/archlinux/man3p/y0.3p new file mode 100644 index 00000000..fef4edc5 --- /dev/null +++ b/upstream/archlinux/man3p/y0.3p @@ -0,0 +1,164 @@ +'\" et +.TH Y0 "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +y0, +y1, +yn +\(em Bessel functions of the second kind +.SH SYNOPSIS +.LP +.nf +#include +.P +double y0(double \fIx\fP); +double y1(double \fIx\fP); +double yn(int \fIn\fP, double \fIx\fP); +.fi +.SH DESCRIPTION +The +\fIy0\fR(), +\fIy1\fR(), +and +\fIyn\fR() +functions shall compute Bessel functions of +.IR x +of the second kind of orders 0, 1, and +.IR n , +respectively. +.P +An application wishing to check for error situations should set +.IR errno +to zero and call +.IR feclearexcept (FE_ALL_EXCEPT) +before calling these functions. On return, if +.IR errno +is non-zero or \fIfetestexcept\fR(FE_INVALID | FE_DIVBYZERO | +FE_OVERFLOW | FE_UNDERFLOW) is non-zero, an error has occurred. +.SH "RETURN VALUE" +Upon successful completion, these functions shall return the relevant +Bessel value of +.IR x +of the second kind. +.P +If +.IR x +is NaN, NaN shall be returned. +.P +If the +.IR x +argument to these functions is negative, \-HUGE_VAL or NaN shall be +returned, and a domain error may occur. +.P +If +.IR x +is 0.0, \-HUGE_VAL shall be returned and a pole error may occur. +.P +If the correct result would cause underflow, 0.0 shall be returned and +a range error may occur. +.P +If the correct result would cause overflow, \-HUGE_VAL or 0.0 shall +be returned and a range error may occur. +.SH ERRORS +These functions may fail if: +.IP "Domain\ Error" 12 +The value of +.IR x +is negative. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [EDOM] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the invalid floating-point exception shall be raised. +.RE +.IP "Pole\ Error" 12 +The value of +.IR x +is zero. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the divide-by-zero floating-point exception shall be +raised. +.RE +.IP "Range\ Error" 12 +The correct result would cause overflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the overflow floating-point exception shall be raised. +.RE +.IP "Range\ Error" 12 +The value of +.IR x +is too large in magnitude, or the correct result would cause +underflow. +.RS 12 +.P +If the integer expression (\fImath_errhandling\fR & MATH_ERRNO) is +non-zero, then +.IR errno +shall be set to +.BR [ERANGE] . +If the integer expression (\fImath_errhandling\fR & MATH_ERREXCEPT) is +non-zero, then the underflow floating-point exception shall be raised. +.RE +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +On error, the expressions (\fImath_errhandling\fR & MATH_ERRNO) and +(\fImath_errhandling\fR & MATH_ERREXCEPT) are independent of each +other, but at least one of them must be non-zero. +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIfeclearexcept\fR\^(\|)", +.IR "\fIfetestexcept\fR\^(\|)", +.IR "\fIisnan\fR\^(\|)", +.IR "\fIj0\fR\^(\|)" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.20" ", " "Treatment of Error Conditions for Mathematical Functions", +.IR "\fB\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . -- cgit v1.2.3